archsight 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 336946fbac9548285ad368125db862c2f1926d99f2f40c1d40ba4155ebe8ca45
-  data.tar.gz: 63ff3e1a973432f98b5ffb66ac9c518a204c0f87d90ee495615cf60bba293cd3
+  metadata.gz: 464d36ecbae64b55e25554f9d60d9c208fb2477ba1910f2318c415eef2cea018
+  data.tar.gz: e423de1798a1a0fc99f16220051139800780e6bd9f01b096bce378dda1ccb25e
 SHA512:
-  metadata.gz: e76456b0f0ed4db22057a4df669953dfcdf7747ed8293ca3092be866e4eea6a4e4c63df6ffeaf6f163da552bf163f409dcb1184a1a493d12e565b0304e527202
-  data.tar.gz: 60a37bef6e039f2bcb20d23fc1010baacdebc65cdded4e8d2f91992583bf60f8245c74175ef26945f3b67e67d6a3421de962c3d8513536376383b55e98bf8afb
+  metadata.gz: 0eb109e3f462b8ec1a23a17ab8c95d5d8bc176a5b54d038e47fa9dcf383e2597c9cc4a540efb1bd876714b279486dfd5a74d1bf1adc8c435a64db07913128890
+  data.tar.gz: 7ce31438036e3addcc8bda4e3587165f13b31399bd7a416323747d1552d9ae910c3e53191f8f7689f7b01a3d84508b9a32cf6cf7486fbb9bde3c0920560283bd

data/CONTRIBUTING.md

@@ -84,7 +84,7 @@ class Archsight::Resources::MyResource < Archsight::Resources::Base
     description: 'Custom field description',
     enum: ['value1', 'value2']
 
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationRequirements, :MotivationRequirement
 end
 ```
 

data/README.md

@@ -91,6 +91,11 @@ archsight web
 claude mcp add --transport sse ionos-architecture http://localhost:4567/mcp/sse
 ```
 
+For a deployed server use its address, for example `claude mcp add --transport sse archsight https://archsight.example.com/mcp/sse`.
+The MCP endpoint accepts any hostname, like the web UI and the API, and has no authentication of its own: if the
+ingress requires a token, pass it with `--header "Authorization: Bearer <token>"`. The ingress must not buffer or
+time out the long-lived SSE connection.
+
 **Available tools:**
 
 - `query` - Search and filter resources using the query language
@@ -101,7 +106,7 @@ claude mcp add --transport sse ionos-architecture http://localhost:4567/mcp/sse
 
 **Macros** such as `{status:yellow WIP}` and `{emoticon:2705}` work inline in pages ([Wiki pages](docs/pages.md#macros)).
 
-**Views and analyses** can be embedded in pages with `![[View/Name]]` / `![[Analysis/Name]]` ([Wiki pages](docs/pages.md#embedding-views-and-analyses)); a view can also be written in place with a ```` ```view ```` block ([inline views](docs/pages.md#inline-views)), and the business requirements of a selection of resources shown with a ```` ```requirements ```` block ([requirements](docs/pages.md#business-requirements-of-a-selection-of-resources)).
+**Views and analyses** can be embedded in pages with `![[View/Name]]` / `![[Analysis/Name]]` ([Wiki pages](docs/pages.md#embedding-views-and-analyses)); a view can also be written in place with a ```` ```view ```` block ([inline views](docs/pages.md#inline-views)), and the requirements of a selection of resources shown with a ```` ```requirements ```` block ([requirements](docs/pages.md#requirements-of-a-selection-of-resources)).
 
 **Images and draw.io diagrams** are plain files in the resources directory and are embedded in markdown with relative
 paths (`![](../img/a.png)`, `![](../../fop/flow.drawio)`); only files of image, draw.io and `.asd` diagram types inside the resources

data/docs/icons.md

@@ -11,16 +11,17 @@ Current icon assignments for each resource type:
 | ApplicationInterface | `usb` | <i class="iconoir-usb"></i> |
 | ApplicationService | `cube` | <i class="iconoir-cube"></i> |
 | BusinessActor | `community` | <i class="iconoir-community"></i> |
-| BusinessConstraint | `prohibition` | <i class="iconoir-prohibition"></i> |
+| BusinessControl | `shield-search` | <i class="iconoir-shield-search"></i> |
 | BusinessProcess | `kanban-board` | <i class="iconoir-kanban-board"></i> |
 | BusinessProduct | `box-iso` | <i class="iconoir-box-iso"></i> |
-| BusinessRequirement | `task-list` | <i class="iconoir-task-list"></i> |
 | ComplianceEvidence | `shield-check` | <i class="iconoir-shield-check"></i> |
 | DataObject | `database` | <i class="iconoir-database"></i> |
 | ApplicationComponent | `component` | <i class="iconoir-component"></i> |
 | TechnologySystemSoftware | `terminal-tag` | <i class="iconoir-terminal-tag"></i> |
 | MotivationGoal | `archery` | <i class="iconoir-archery"></i> |
 | MotivationOutcome | `badge-check` | <i class="iconoir-badge-check"></i> |
+| MotivationRequirement | `task-list` | <i class="iconoir-task-list"></i> |
+| MotivationConstraint | `prohibition` | <i class="iconoir-prohibition"></i> |
 | MotivationStakeholder | `user-crown` | <i class="iconoir-user-crown"></i> |
 | TechnologyNode | `server-connection` | <i class="iconoir-server-connection"></i> |
 | StrategyCapability | `strategy` | <i class="iconoir-strategy"></i> |

data/docs/index.md.erb

@@ -24,21 +24,22 @@ The following diagram shows all resource types organized by layer and their rela
 
 ### Motivation Layer
 
-Resources representing stakeholders, goals, and outcomes that drive architectural decisions.
+Resources representing stakeholders, goals, outcomes, requirements, and constraints that drive architectural decisions.
 
 - [MotivationStakeholder](/doc/resources/motivation_stakeholder) - Roles with interests in the architecture
 - [MotivationGoal](/doc/resources/motivation_goal) - High-level statements of intent
 - [MotivationOutcome](/doc/resources/motivation_outcome) - End results or consequences
+- [MotivationRequirement](/doc/resources/motivation_requirement) - Compliance, legal and functional requirements
+- [MotivationConstraint](/doc/resources/motivation_constraint) - Limitations and restrictions
 
 ### Business Layer
 
-Resources representing business processes, actors, and products.
+Resources representing business processes, actors, products, and the controls that guide processes.
 
 - [BusinessActor](/doc/resources/business_actor) - Teams and organizations
 - [BusinessProcess](/doc/resources/business_process) - Structured business workflows
 - [BusinessProduct](/doc/resources/business_product) - Products offered to customers
-- [BusinessRequirement](/doc/resources/business_requirement) - Business and compliance requirements
-- [BusinessConstraint](/doc/resources/business_constraint) - Limitations and restrictions
+- [BusinessControl](/doc/resources/business_control) - Controls that guide business processes
 
 ### Strategy Layer
 

data/docs/modeling.md

@@ -52,6 +52,8 @@ Model **why** the architecture exists.
 | MotivationStakeholder | For roles that have interest in architecture outcomes (CTO, Security Team, Customers) |
 | MotivationGoal | For high-level objectives ("Achieve SOC 2 compliance", "Reduce latency") |
 | MotivationOutcome | For measurable results ("99.9% availability", "Sub-100ms response") |
+| MotivationRequirement | For must-have capabilities (compliance, functional needs) |
+| MotivationConstraint | For limitations (budget, regulations, technical debt) |
 
 **Example chain:** Stakeholder "Security Team" → hasConcern → Goal "Achieve Compliance" → realizes → Requirement "Encrypt data at rest"
 
@@ -64,11 +66,12 @@ Model **who** does **what** in business terms.
 | BusinessActor | For teams, departments, or organizations |
 | BusinessProcess | For workflows that produce business value |
 | BusinessProduct | For offerings to customers (cloud services, APIs) |
-| BusinessRequirement | For must-have capabilities (compliance, functional needs) |
-| BusinessConstraint | For limitations (budget, regulations, technical debt) |
+| BusinessControl | For controls that guide a process (access review, change approval), with an owner and executors |
 
 **Example chain:** Actor "Platform Team" → performedBy → Process "Incident Response" → servedBy → Service "Monitoring"
 
+**Controls:** Process "Incident Response" → guidedBy → Control "Escalation Review" → ownedBy / executedBy → Actor "Platform Team". How controls, requirements and evidence fit together is described under Relation Patterns below.
+
 ### Strategy Layer
 
 Model strategic **capabilities**.
@@ -114,7 +117,7 @@ Model **infrastructure** and **code**.
 Shows how abstract concepts become concrete:
 
 ```
-BusinessRequirement
+MotivationRequirement
        ↓ realizes
 ApplicationService
        ↓ realizedThrough
@@ -135,12 +138,63 @@ TechnologyService
 TechnologySystemSoftware
 ```
 
+### Requirements, Controls and Evidence
+
+A requirement is the point where the process side and the application side of compliance meet:
+
+```
+Process side                                Application side
+
+BusinessProcess                             ApplicationService / ApplicationComponent
+       ↓ guidedBy                                  ↓ realizes / plans
+BusinessControl                                    ↓ evidencedBy
+       ↓ satisfies                          ComplianceEvidence
+       ↓                                           ↓ satisfies
+       └────────────→ MotivationRequirement ←────────┘
+```
+
+| Kind | Answers | Key relations |
+|------|---------|---------------|
+| MotivationRequirement | What must hold? | satisfied by controls and evidence; realized or planned by applications |
+| BusinessControl | What do we do about it, who does it, how often? | a process is `guidedBy` it; `ownedBy` and `executedBy` actors; `satisfies` requirements; `evidencedBy` evidence |
+| ComplianceEvidence | How is it met, how can it be shown? | `satisfies` requirements; `evidencedBy` from an application, a technology element or a control |
+
+How to model it:
+
+- **Process side.** Model a control once, let every process it governs point to it with `guidedBy`, and link it with `satisfies` to each requirement it addresses. Give it an owner (the accountable actor) and executors (the actors carrying it out). The `control/status` and `control/frequency` filters find, for example, the controls that are only partially implemented.
+- **Application side.** Whether an application implements a requirement is stated on the application (`realizes`, `plans`, `evidencedBy`), never on the control. Evidence is per resource and requirement: it says how *this* service or component meets *that* requirement.
+- **Evidence of a control.** A control can be `evidencedBy` evidence too. Use it for the records the control itself produces (reviews, diagrams, change history, audit logs) and set `evidence/type` to `process`, `documentation` or `audit-log`. Evidence that an application meets a requirement is linked from the application, not from a control.
+- **Reading it back.** A requirement's page lists its controls and evidence as incoming `satisfies` relations. The "Requirements" table of an application page and the `requirements` blocks list what applications implement (`realizes`, `partiallyRealizes`, `plans`); controls are not part of that table.
+
+```yaml
+# process side
+kind: BusinessProcess
+metadata: { name: Process:ChangeManagement }
+spec:
+  guidedBy:
+    businessControls: [Control:ChangeApproval]
+---
+kind: BusinessControl
+metadata: { name: Control:ChangeApproval }
+spec:
+  ownedBy:    { businessActors: [Team:Management] }
+  executedBy: { businessActors: [Team:Operations] }
+  satisfies:  { motivationRequirements: [Requirement:ChangeTraceability] }
+---
+# application side
+kind: ApplicationService
+metadata: { name: Deployment }
+spec:
+  realizes:    { motivationRequirements: [Requirement:ChangeTraceability] }
+  evidencedBy: { complianceEvidences: [Evidence:DeploymentAuditLog] }
+```
+
 ### Compliance Chain
 
 Shows how requirements are satisfied:
 
 ```
-BusinessRequirement
+MotivationRequirement
        ↑ satisfies
 ComplianceEvidence
        ↑ evidencedBy
@@ -151,6 +205,44 @@ Technology elements such as a Kubernetes cluster runtime can plan, realize and b
 for requirements directly, so the requirement does not have to be attached to a placeholder
 ApplicationService. Applications deployed on them point to the TechnologyService with `servedBy`.
 
+ApplicationComponents can be evidenced as well (`realizes` / `plans motivationRequirements`, `evidencedBy
+complianceEvidences`), so requirements can be answered per component and not only per service.
+
+A ComplianceEvidence answers "how is the requirement met" in structured markdown fields next to
+`architecture/description` (kept as a short summary): `evidence/mechanism`, `evidence/coverage`,
+`evidence/operatorView` (does it hold against operators or only against other tenants),
+`evidence/verification`, `evidence/gaps` and `evidence/sources`. Because they are separate annotations they can be
+queried, for example `ComplianceEvidence: evidence/gaps =~ "needs review"`.
+
+### Derived References
+
+Text and diagrams already say which resources they are about, so archsight turns that into relations instead of asking you
+to repeat it in YAML. There are two, and they are never written in a file:
+
+| Relation | Comes from | Where |
+|----------|------------|-------|
+| `mentions` | `[[Target]]`, `[[Kind/Name]]` links and `![[View/Name]]` embeds | the content of a page, the description of any resource, any markdown annotation |
+| `depicts` | the `resource "..."` of the nodes of a diagram | ```` ```asd ```` blocks and `![](file.asd)` files in those texts, and the `architecture/diagram` of any resource |
+
+```
+Page "Architecture overview"  --mentions-->  ApplicationComponent "Core:Database"     ([[Core:Database]])
+Page "Architecture overview"  --depicts--->  ApplicationComponent "Web:API"           (resource "Web:API" in a diagram)
+```
+
+They are rebuilt on every load, so they cannot drift from the text. They show on both sides: a resource lists the pages
+that mention and depict it under Relations ("Page / mentions"), and a page lists what it refers to. Only an exact name counts: a
+page by its name or title, `Kind/Name`, or a resource name that exists once. Part of a name, a name that exists in several
+kinds, and an unknown name do not make a relation (`archsight lint` reports unknown links in pages). Links in code are shown as
+written and do not count, and neither does a resource referring to itself. Views and requirements blocks pick resources with a
+query when they run, so they name nothing.
+
+Derived relations are followed like written ones: queries (`ApplicationComponent: <- Page`, `Page: -> ApplicationComponent`),
+transitive queries and impact analysis. A page that mentions a component therefore shows up when you ask what a change to the
+component affects, which tells you which pages to update, and a resource that only a page mentions is not an orphan
+(`<- none`). To leave them out of a query, exclude the verbs: `ApplicationComponent: ~{!mentions,depicts}> TechnologyArtifact`.
+Computed annotations (costs, teams, repositories) follow written relations only, so a link in a text never changes a number.
+They are not part of the editor's relation form, and `mentions:` or `depicts:` in a file is an unknown verb.
+
 ## Annotation Best Practices
 
 Use annotations to capture metadata:
@@ -194,7 +286,7 @@ relations:
 ### Compliance Mapping
 
 ```yaml
-kind: BusinessRequirement
+kind: MotivationRequirement
 name: DataEncryption
 annotations:
   requirement/reference: c5-2020, gdpr-2018
@@ -204,3 +296,28 @@ relations:
     outcomes:
       - DataProtection
 ```
+
+## Renamed Kinds
+
+Requirements and constraints are Motivation elements in ArchiMate, so their kinds are named that way:
+
+| Old | New |
+|-----|-----|
+| `BusinessRequirement` | `MotivationRequirement` |
+| `BusinessConstraint` | `MotivationConstraint` |
+| relation key `businessRequirements` | `motivationRequirements` |
+| relation key `businessConstraints` | `motivationConstraints` |
+
+Both kinds moved from the Business to the Motivation layer. Their annotations (`requirement/*`) are unchanged.
+
+For now the old names keep working: files with `kind: BusinessRequirement` or `businessRequirements:` keys load as they are, queries such as `BusinessRequirement: requirement/priority == "must"` and `~> BusinessRequirement` still match, and old links to `/kinds/BusinessRequirement/...` still open. Everything shown (the UI, the API, files written by the inline editor) uses the new names.
+
+`archsight lint` lists every use of an old name as a deprecation, with the file and line, without failing. Replace them, for example with a find and replace over your resources directory (YAML files and the queries in markdown pages):
+
+```bash
+find resources \( -name '*.yaml' -o -name '*.md' \) -exec sed -i.bak \
+  -e 's/BusinessRequirement/MotivationRequirement/g' -e 's/BusinessConstraint/MotivationConstraint/g' \
+  -e 's/businessRequirements/motivationRequirements/g' -e 's/businessConstraints/motivationConstraints/g' {} +
+```
+
+The old names will be removed in a future release.

data/docs/pages.md

@@ -171,14 +171,14 @@ It loads and runs in the browser like any embed; the server only writes `<div cl
 data-fields data-sort data-type>` around the source. A block that is not a valid View (broken YAML, missing or
 unparsable query, unknown `view/*` key or type) shows an error box with the source, and `archsight lint` reports it.
 
-### Business requirements of a selection of resources
+### Requirements of a selection of resources
 
-The "Business Requirements" table of an instance page (the requirements it `realizes`, `partiallyRealizes` or `plans`,
+The "Requirements" table of an instance page (the requirements it `realizes`, `partiallyRealizes` or `plans`,
 with status, priority and story) can be put on a page for any selection of resources with a ```` ```requirements ```` block:
 
 ````markdown
 ```requirements
-title: Requirements of the backup services     # optional, default "Business Requirements"
+title: Requirements of the backup services     # optional, default "Requirements"
 of: 'ApplicationService: name =~ "Backup"'     # required: query selecting the resources
 priority: must                                 # optional: must, should, may (one value or a list)
 status: [implemented, partial]                 # optional: implemented, partial, planned
@@ -193,6 +193,15 @@ data-status>` around the source): the frontend loads the rows from `GET /api/v1/
 never runs the query. A block with a missing or unparsable `of`, an unknown key, priority or status shows an error box with the
 source, and `archsight lint` reports it.
 
+## What a page refers to
+
+What a page says about the architecture becomes relations without anything to write: `[[Core:Database]]` or `[[Kind/Name]]` in the
+text makes the page `mention` that resource, and a resource in a diagram of the page (an ```` ```asd ```` block or an embedded
+`.asd` file) makes the page `depict` it. The resource then lists the page under Relations, and the page lists the resource, so you
+can see which pages talk about a component, and which pages to review when it changes (impact analysis includes them). Only exact
+names count and links in code are ignored. The same applies to the description and the diagram of every other resource. See
+[Derived references](modeling.md#derived-references).
+
 ## Macros
 
 Inline macros are written `{name:arguments}` and named like the macros of Confluence. They work inside a sentence, a

data/docs/search.md

@@ -121,7 +121,7 @@ Examples:
     -> ApplicationInterface              # exposes an interface
     -> "Kubernetes:RestAPI"              # exposes specific interface
     <- ApplicationComponent              # referenced by a component
-    ~> BusinessRequirement               # transitively reaches requirement
+    ~> MotivationRequirement               # transitively reaches requirement
     -> none & <- none                    # orphan (no relations)
     TechnologyArtifact: <- none          # unreferenced artifacts
 
@@ -175,6 +175,13 @@ Examples:
     # Find artifacts with NO maintainedBy relations
     TechnologyArtifact: -{maintainedBy}> none
 
+    # Pages that mention a component, and the components they depict
+    ApplicationComponent: <{mentions}- Page
+    Page: -{depicts}> ApplicationComponent
+
+    # Leave the derived relations (links in text, nodes of diagrams) out of a traversal
+    ApplicationComponent: ~{!mentions,depicts}> TechnologyArtifact
+
 ## Sub-Query Targets
 
 Use `$(expression)` to dynamically find relation targets based on a query:
@@ -249,7 +256,7 @@ Large Go codebases:
 
 Resources with compliance chain:
 
-    ~> BusinessRequirement
+    ~> MotivationRequirement
 
 Complex query with grouping:
 

data/docs/togaf.md

@@ -124,6 +124,10 @@ The metamodel defines architectural entities and their relationships across all
 
 - **Principle**, **Constraint**, **Requirement**, **Gap**, **Work Package**, **Location**
 
+**Governance:**
+
+- **Control**: a decision-making step with accountability and authority, applied to a process or function. ArchiMate has no element for it; Archsight models it as `BusinessControl`, which a `BusinessProcess` is `guidedBy`
+
 ### Critical Relationships
 
 1. **Traceability**: Drivers → Goals → Objectives → Course of Action → Business Elements → Applications → Technology

data/lib/archsight/annotations/relation_resolver.rb

@@ -11,6 +11,17 @@
 # - Symbol: Simple kind filter (e.g., :TechnologyArtifact)
 # - String: Query selector (e.g., 'TechnologyArtifact: activity/status == "active"')
 class Archsight::Annotations::ComputedRelationResolver
+  # The instances that refer to a resource through relations that are written in files. Computed annotations sum up the
+  # modelled architecture (costs, teams, repositories): what a page or a description merely mentions or depicts (see
+  # Archsight::References) must not change them, so they follow modelled relations only.
+  def self.modelled_references(inst)
+    (inst.references || []).filter_map do |ref|
+      next ref unless ref.is_a?(Hash)
+
+      ref[:instance] unless Archsight::Resources::DERIVED_VERBS.include?(ref[:verb])
+    end
+  end
+
   MAX_DEPTH = 10
 
   # TraversalCache holds what can be shared between all resolvers of one computation run: the unfiltered
@@ -83,9 +94,9 @@ class Archsight::Annotations::ComputedRelationResolver
 
     def neighbours(inst, direction)
       if direction == :outgoing
-        inst.class.relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
+        inst.class.declared_relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
       else
-        (inst.references || []).filter_map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }
+        Archsight::Annotations::ComputedRelationResolver.modelled_references(inst)
       end
     end
   end
@@ -103,7 +114,7 @@ class Archsight::Annotations::ComputedRelationResolver
   def outgoing(filter = nil)
     results = []
 
-    @instance.class.relations.each do |_verb, kind_name, _klass_name|
+    @instance.class.declared_relations.each do |_verb, kind_name, _klass_name|
       rels = @instance.relations(_verb, kind_name)
       rels.each do |rel|
         results << rel if matches_filter?(rel, filter)
@@ -127,9 +138,7 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param filter [Symbol, String, nil] Optional kind filter (Symbol) or query selector (String)
   # @return [Array] Array of instances that reference this one
   def incoming(filter = nil)
-    refs = @instance.references || []
-    # Extract instances from reference hashes
-    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
+    instances = self.class.modelled_references(@instance).compact
 
     if filter.nil?
       instances

data/lib/archsight/cli.rb

@@ -127,6 +127,12 @@ module Archsight
       linter = Archsight::Linter.new(db)
       errors = linter.validate
 
+      warnings = linter.warnings
+      if warnings.any?
+        puts "Deprecations (#{warnings.count}):"
+        warnings.each { |warning| puts "  #{warning}" }
+      end
+
       if errors.any?
         puts "Validation Errors (#{errors.count}):"
         errors.each { |error| display_error_with_context(error) }

data/lib/archsight/database.rb

@@ -5,6 +5,7 @@ require_relative "graph"
 require_relative "resources"
 require_relative "page_loader"
 require_relative "query"
+require_relative "references"
 
 module Archsight
   # LineReference combines a path and line reference
@@ -40,12 +41,19 @@ module Archsight
     end
   end
 
+  # Deprecation is a use of a renamed kind or relation key that was accepted under its old name
+  Deprecation = Struct.new(:ref, :message) do
+    def to_s
+      "#{ref}: #{message}"
+    end
+  end
+
   # Database loads yaml files and folders to create an in-memory representation
   # of the structure. The loading and parsing of files will raise errors
   # if invalid data is passed.
   class Database
     attr_accessor :instances, :verbose, :verify, :compute_annotations, :only_kinds
-    attr_reader :path
+    attr_reader :path, :deprecations
 
     def initialize(path, verbose: false, verify: true, compute_annotations: true, only_kinds: nil)
       @path = path
@@ -54,10 +62,12 @@ module Archsight
       @compute_annotations = compute_annotations
       @only_kinds = only_kinds
       @instances = {}
+      @deprecations = []
     end
 
     def reload!
       @instances = {}
+      @deprecations = []
 
       # load all resources
       Dir.glob(File.join(@path, "**/*.{yaml,md}")).each do |path|
@@ -67,6 +77,7 @@ module Archsight
       end
 
       verify! if @verify
+      derive_references! if @verify
       compute_all_annotations! if @verify && @compute_annotations
     rescue Psych::SyntaxError => e
       # Wrap YAML syntax errors in ResourceError for consistent handling
@@ -118,12 +129,49 @@ module Archsight
 
       kind = obj["kind"] || raise("kind not defined")
       klass = Archsight::Resources[kind] || raise("#{kind} is not a valid kind")
+      accept_old_names(obj)
       inst = klass.new(obj, @current_ref)
       raise("metadata name of #{kind} not present") if inst.name.to_s.strip.empty?
 
       inst
     end
 
+    # Documents may still use the old name of a renamed kind and the old relation keys. They are rewritten to the
+    # current names here, so everything after loading only sees those, and each rewrite is kept as a deprecation
+    # (reported by `archsight lint`).
+    def accept_old_names(obj)
+      kind = obj["kind"]
+      current = Archsight::Resources.canonical(kind)
+      if current != kind
+        deprecate("kind '#{kind}' is renamed to '#{current}'")
+        obj["kind"] = current
+      end
+
+      return unless obj["spec"].is_a?(Hash)
+
+      obj["spec"].each do |verb, keys|
+        next unless keys.is_a?(Hash)
+
+        Archsight::Resources::RELATION_KEY_ALIASES.each do |old_key, new_key|
+          next unless keys.key?(old_key)
+
+          deprecate("relation key '#{old_key}' under '#{verb}' is renamed to '#{new_key}'")
+          keys[new_key] = (Array(keys[new_key]) + Array(keys.delete(old_key))).uniq
+        end
+      end
+    end
+
+    def deprecate(message)
+      @deprecations << Deprecation.new(@current_ref, "#{message} (the old name will be removed in a future release)")
+    end
+
+    # Whether a document of this kind is wanted by the only_kinds filter, whichever of its names either side uses
+    def kind_wanted?(kind)
+      return true unless @only_kinds
+
+      @only_kinds.map { |k| Archsight::Resources.canonical(k) }.include?(Archsight::Resources.canonical(kind))
+    end
+
     def load_file(path)
       File.open(path, "r") do |f|
         YAML.parse_stream(f) do |node|
@@ -132,7 +180,7 @@ module Archsight
           next unless obj # skip empty / unknown documents
 
           # Skip resources that don't match only_kinds filter
-          next if @only_kinds && !@only_kinds.include?(obj["kind"])
+          next unless kind_wanted?(obj["kind"])
 
           self << create_valid_instance(obj)
         end
@@ -186,7 +234,7 @@ module Archsight
     end
 
     def verify_instance_relations!(inst)
-      inst.class.relations.each do |verb, kind, klass_name|
+      inst.class.declared_relations.each do |verb, kind, klass_name|
         rels = inst.relations(verb, kind).map do |rel_name|
           rel_klass = Archsight::Resources[klass_name] || raise_for(inst, "#{klass_name} is not a valid relation kind")
           kind_display = rel_klass.to_s.sub(/^Archsight::Resources::/, "")
@@ -197,6 +245,12 @@ module Archsight
       end
     end
 
+    # Adds the relations that the text and the diagrams of the resources imply (`mentions`, `depicts`), after all
+    # written relations are resolved and before the computed annotations are calculated, which follow relations.
+    def derive_references!
+      Archsight::References.derive!(self)
+    end
+
     # Compute all computed annotations for all instances
     def compute_all_annotations!
       manager = Archsight::Annotations::ComputedManager.new(self)

data/lib/archsight/diagram.rb

@@ -44,6 +44,13 @@ module Archsight
       time(profile, :render) { Renderer.render(graph, layout, relation_filter: relation_filter, style: style, id_prefix: id_prefix) }
     end
 
+    # The `resource "..."` references of the nodes of a diagram source, in order and without duplicates. Parses and
+    # builds the graph but does not lay it out, so it is cheap enough to run over every diagram of a model.
+    # @raise [Archsight::Diagram::Error] if the source is not a valid diagram
+    def self.resource_references(source)
+      Graph.build(Parser.parse(source)).nodes_by_id.values.filter_map { |node| node.attrs["resource"] }.uniq
+    end
+
     def self.time(profile, key)
       return yield unless profile
 

data/lib/archsight/documentation.rb

@@ -104,7 +104,7 @@ module Archsight
           # Skip kinds not in a displayed layer
           next unless LAYER_ORDER.include?(klass.layer)
 
-          klass.relations.each do |verb, _relation_kind, target_klass|
+          klass.declared_relations.each do |verb, _relation_kind, target_klass|
             # Skip relations to excluded kinds
             next if EXCLUDED_KINDS.include?(target_klass.to_s)
 
@@ -149,13 +149,16 @@ module Archsight
       end
 
       def generate_relations_table(klass)
-        return "_No relations defined._" if klass.relations.empty?
+        derived = "Every resource also has the derived relations #{Archsight::Resources::DERIVED_VERBS.map { |v| "`#{v}`" }.join(" and ")} " \
+                  "towards any kind: they follow from links in its text and from its diagrams, so they are not written in files " \
+                  "(see the Modeling Guide)."
+        return "_No relations defined._\n\n#{derived}" if klass.declared_relations.empty?
 
         rows = ["| Relation | Target | Kind |", "|----------|--------|------|"]
-        klass.relations.each do |verb, kind, target_klass|
+        klass.declared_relations.each do |verb, kind, target_klass|
           rows << "| #{verb} | #{target_klass} | #{kind} |"
         end
-        rows.join("\n")
+        "#{rows.join("\n")}\n\n#{derived}"
       end
 
       def format_values(annotation)

data/lib/archsight/editor.rb

@@ -21,7 +21,7 @@ module Archsight
     def build_resource(kind:, name:, annotations: {}, relations: [])
       resource = {
         "apiVersion" => "architecture/v1alpha1",
-        "kind" => kind,
+        "kind" => Archsight::Resources.canonical(kind), # saving a resource that had the old name migrates it
         "metadata" => {
           "name" => name
         }
@@ -129,7 +129,7 @@ module Archsight
       klass = Archsight::Resources[kind]
       return [] unless klass
 
-      klass.relations
+      klass.declared_relations # derived relations are not written in files
     end
 
     # Get unique verbs for a resource kind's relations

data/lib/archsight/helpers/requirements_blocks.rb

@@ -5,7 +5,7 @@ require_relative "fenced_blocks"
 
 module Archsight
   module Helpers
-    # Turns ```requirements fenced blocks in rendered markdown into the table of business requirements of a
+    # Turns ```requirements fenced blocks in rendered markdown into the table of requirements of a
     # selection of resources (see Archsight::Requirements):
     #
     #   ```requirements

data/lib/archsight/helpers/resource_resolver.rb

@@ -38,7 +38,7 @@ module Archsight
         klass = Archsight::Resources[kind]
         return [] unless klass && @database.instances.fetch(klass, {}).key?(name)
 
-        [[kind, name]]
+        [[Archsight::Resources.canonical(kind), name]] # a renamed kind is linked under its new name
       end
 
       def in_any_kind(name)

data/lib/archsight/helpers/wiki_links.rb

@@ -64,6 +64,17 @@ module Archsight
         found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
       end
 
+      # Like target_for, but only an exact name counts: a page by name or title, `Kind/Name`, or a resource name that
+      # exists in one kind. A target that only matches part of a name does not name anything. For relations that are
+      # derived from text, where a wrong guess would be a wrong relation.
+      def exact_target_for(target)
+        page = find_page(target)
+        return page if page
+
+        found = @resolver.find(target)
+        found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
+      end
+
       # Page path for a page name, nil if there is no such page
       def page_path(page)
         "/pages/#{ERB::Util.url_encode(page.name)}"