archsight 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 336946fbac9548285ad368125db862c2f1926d99f2f40c1d40ba4155ebe8ca45
-  data.tar.gz: 63ff3e1a973432f98b5ffb66ac9c518a204c0f87d90ee495615cf60bba293cd3
+  metadata.gz: b601281c3dc26c95647876457b96e590146aee23b762d14034ed2ae5f0953710
+  data.tar.gz: 7c271d26e8def3f7e85d82210ebda0d45628e280c1bb58832b81f2900c3e1097
 SHA512:
-  metadata.gz: e76456b0f0ed4db22057a4df669953dfcdf7747ed8293ca3092be866e4eea6a4e4c63df6ffeaf6f163da552bf163f409dcb1184a1a493d12e565b0304e527202
-  data.tar.gz: 60a37bef6e039f2bcb20d23fc1010baacdebc65cdded4e8d2f91992583bf60f8245c74175ef26945f3b67e67d6a3421de962c3d8513536376383b55e98bf8afb
+  metadata.gz: 416c904c7b8ecc1c44527b226fe7e6c7697c03d905d855db532bb80f1bd5ff0ff1277c770947eed411a6ca7cae7dafd8e32085690d72a4235c73bd4c1f35950b
+  data.tar.gz: 9c22b78187060cdc3606b4f423a38b79f84edcee6cb1d6f1446348a9da46dc088bedb4f537c809aad28c2db33f875d490637c4dcc13b57b4ee0ccc76822a0193

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,24 +11,51 @@ 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> |
+| ApplicationEvent | `bell-notification` | <i class="iconoir-bell-notification"></i> |
+| BusinessControl | `shield-search` | <i class="iconoir-shield-search"></i> |
+| BusinessEvent | `flash` | <i class="iconoir-flash"></i> |
+| BusinessRole | `user-badge-check` | <i class="iconoir-user-badge-check"></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> |
+| MotivationAssessment | `stats-up-square` | <i class="iconoir-stats-up-square"></i> |
+| MotivationDriver | `fire-flame` | <i class="iconoir-fire-flame"></i> |
+| ImplementationDeliverable | `package` | <i class="iconoir-package"></i> |
+| ImplementationEvent | `calendar-check` | <i class="iconoir-calendar-check"></i> |
+| ImplementationGap | `git-compare` | <i class="iconoir-git-compare"></i> |
+| ImplementationPlateau | `packages` | <i class="iconoir-packages"></i> |
+| ImplementationWorkPackage | `hammer` | <i class="iconoir-hammer"></i> |
 | MotivationGoal | `archery` | <i class="iconoir-archery"></i> |
 | MotivationOutcome | `badge-check` | <i class="iconoir-badge-check"></i> |
+| MotivationPrinciple | `book` | <i class="iconoir-book"></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> |
 | TechnologyArtifact | `puzzle` | <i class="iconoir-puzzle"></i> |
+| TechnologyEvent | `warning-triangle` | <i class="iconoir-warning-triangle"></i> |
 | TechnologyInterface | `data-transfer-both` | <i class="iconoir-data-transfer-both"></i> |
 | TechnologyService | `cloud` | <i class="iconoir-cloud"></i> |
 | View | `view-grid` | <i class="iconoir-view-grid"></i> |
 
+## Layer Colours
+
+Icons and graph nodes take the colour of their layer.
+
+| Layer | Colour | Graph (light) | Icon |
+|-------|--------|---------------|------|
+| Strategy | orange | `#F4A261` | `#D4824A` |
+| Motivation | purple | `#CE93D8` | `#AB47BC` |
+| Business | yellow | `#F9DC5C` | `#D4B83C` |
+| Application | blue | `#6CBEED` | `#4A9ECD` |
+| Technology | green | `#8AC926` | `#7AB316` |
+| Implementation & Migration | rose | `#F48FB1` | `#E0527F` |
+| Other | gray | `#CCCCCC` | `#999999` |
+
 ## Icon Categories
 
 ### Technology & Development

data/docs/index.md.erb

@@ -24,21 +24,27 @@ 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
+- [MotivationDriver](/doc/resources/motivation_driver) - Threats, opportunities and other drivers
+- [MotivationAssessment](/doc/resources/motivation_assessment) - Risks, vulnerabilities and findings
+- [MotivationPrinciple](/doc/resources/motivation_principle) - Policies and principles
 
 ### 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
+- [BusinessRole](/doc/resources/business_role) - Responsibilities that actors take on
 - [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
+- [BusinessEvent](/doc/resources/business_event) - Threat events, loss events and triggers
 
 ### Strategy Layer
 
@@ -53,6 +59,7 @@ Resources representing application services, components, and interfaces.
 - [ApplicationService](/doc/resources/application_service) - High-level application services
 - [ApplicationComponent](/doc/resources/application_component) - Logical parts of services
 - [ApplicationInterface](/doc/resources/application_interface) - APIs and interfaces between components
+- [ApplicationEvent](/doc/resources/application_event) - Threat events, loss events and triggers of applications
 - [DataObject](/doc/resources/data_object) - Data structures and schemas
 
 ### Technology Layer
@@ -62,9 +69,20 @@ Resources representing technology infrastructure and artifacts.
 - [TechnologyService](/doc/resources/technology_service) - Infrastructure services
 - [TechnologyArtifact](/doc/resources/technology_artifact) - Source code repositories
 - [TechnologyInterface](/doc/resources/technology_interface) - Technical interfaces
+- [TechnologyEvent](/doc/resources/technology_event) - Infrastructure events, scan findings and outages
 - [TechnologySystemSoftware](/doc/resources/technology_system_software) - Logical infrastructure components
 - [TechnologyNode](/doc/resources/technology_node) - Physical infrastructure
 
+### Implementation & Migration Layer
+
+Resources representing change: work, results, milestones and the states of the architecture between them.
+
+- [ImplementationWorkPackage](/doc/resources/implementation_work_package) - Projects, measures and remediation
+- [ImplementationDeliverable](/doc/resources/implementation_deliverable) - Results of work packages
+- [ImplementationEvent](/doc/resources/implementation_event) - Milestones, go-lives and deadlines
+- [ImplementationPlateau](/doc/resources/implementation_plateau) - Baseline, transition and target states
+- [ImplementationGap](/doc/resources/implementation_gap) - Differences between plateaus
+
 ### Other
 
 - [ComplianceEvidence](/doc/resources/compliance_evidence) - Evidence for compliance requirements

data/docs/modeling.md

@@ -18,6 +18,34 @@ Application Layer   What software supports the business
 Technology Layer    How software is built and deployed
 ```
 
+## Direction of Relations
+
+Model and read the architecture **top-down**: Motivation, Strategy, Business, Application, Technology; the
+Implementation & Migration layer describes change across all of them. A relation is written on an element and points
+to what that element depends on, is served by, or is answered by. Following relations from a high-level element
+therefore walks down to people, code and infrastructure, and the relations form a DAG: nothing may lead back to where
+it started. `archsight lint` reports every cycle (only `dependsOn` is exempt, because components may depend on each
+other at runtime).
+
+There are two families of verbs:
+
+| Family | Verbs | Written on | Points to |
+|--------|-------|------------|-----------|
+| Responsibility and provider (down) | `performedBy`, `ownedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `realizedThrough`, `exposes`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
+| Realization (up) | `realizes`, `partiallyRealizes`, `plans`, `satisfies`, `evidencedBy` (on the evidenced element), `provides` | the concrete element | the abstract element it answers to (requirement, goal, capability, plateau) |
+
+Rules:
+
+- A pair of kinds never has the same relation in both directions: a goal `realizes` a requirement, a requirement does not
+  `realize` a goal. Reverse relations are shown for free as incoming relations.
+- Responsibility ends at the actor: process, control, risk, policy, work package point to a `BusinessRole`, the role
+  points to the `BusinessActor` that holds it, and the actor points to nothing further.
+- The docs draw realization chains top-down ("Requirement, down to Service") while the data is stored on the concrete
+  element, so the file of a service says what it realizes.
+- `mentions` and `depicts` are not part of this structure. They are derived from the text and diagrams of a resource
+  (never written in a file) and show how things are linked sideways, in prose and pictures. They neither follow nor
+  contradict the direction above and are left out of the cycle check.
+
 ## Starting Points
 
 ### Top-Down Modeling
@@ -52,6 +80,11 @@ 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) |
+| MotivationDriver | For threats, opportunities, regulation and market forces that motivate action (`driver/type`) |
+| MotivationAssessment | For risks, vulnerabilities, findings and supplier or protection-need analyses (`assessment/type`) |
+| MotivationPrinciple | For policies, guidelines and architecture principles (`principle/type`) |
 
 **Example chain:** Stakeholder "Security Team" → hasConcern → Goal "Achieve Compliance" → realizes → Requirement "Encrypt data at rest"
 
@@ -62,12 +95,33 @@ Model **who** does **what** in business terms.
 | Resource | When to Use |
 |----------|-------------|
 | BusinessActor | For teams, departments, or organizations |
+| BusinessRole | For responsibilities held by actors: control owner, risk owner, information security officer (`role/type`) |
 | 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 |
+| BusinessEvent | For things that happen in the business: threat events, loss events, incidents, triggers (`event/type`) |
+
+**Example chain:** Process "Incident Response" → performedBy → Actor "Platform Team"; Process "Incident Response" → servedBy → Service "Monitoring"
+
+**Roles:** Process "Incident Response" → performedBy → Role "Incident Manager" → performedBy → Actor "Platform Team". Controls, risks, policies and work packages use `ownedBy` (and controls `executedBy`) the same way. Use a role where the responsibility has a name of its own and should survive a change of team; pointing straight at an actor stays valid.
+
+**Controls:** Process "Incident Response" → guidedBy → Control "Escalation Review" → ownedBy / executedBy → Role or Actor. How controls, requirements and evidence fit together is described under Relation Patterns below.
 
-**Example chain:** Actor "Platform Team" → performedBy → Process "Incident Response" → servedBy → Service "Monitoring"
+### Implementation & Migration Layer
+
+Model **change**: what is done, what it delivers and how the architecture looks before and after.
+
+| Resource | When to Use |
+|----------|-------------|
+| ImplementationWorkPackage | For projects, measures, remediation of risks and findings, audit programmes (`workpackage/type`, status, due date) |
+| ImplementationDeliverable | For the results of work packages: documents, systems, process changes, evidence (`deliverable/type`) |
+| ImplementationEvent | For milestones, go-lives and deadlines (`event/type`) |
+| ImplementationPlateau | For a state of the architecture: baseline, transition, target (`plateau/type`) |
+| ImplementationGap | For the difference between two plateaus (`gap/status`, `gap/impact`) |
+
+**Migration path:** Plateau "Baseline" → triggers → Plateau "Target"; Gap → compares → both plateaus; Work Package → realizes → Deliverable → realizes → Plateau "Target"; Gap → closedBy → Work Package.
+
+**Remediation:** Assessment "Risk" → mitigatedBy → Work Package → realizes → Deliverable (type `evidence`) → realizes → ComplianceEvidence. Group by `risk/domain` to see the plan of one domain, filter by `workpackage/status` and `workpackage/due` for what is open or late.
 
 ### Strategy Layer
 
@@ -114,7 +168,7 @@ Model **infrastructure** and **code**.
 Shows how abstract concepts become concrete:
 
 ```
-BusinessRequirement
+MotivationRequirement
        ↓ realizes
 ApplicationService
        ↓ realizedThrough
@@ -135,12 +189,157 @@ 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] }
+```
+
+### Security and Risk
+
+Security and risk are modelled with the elements above, following the risk and security overlay of the Open Group
+white paper [Modeling Enterprise Risk Management and Security with the ArchiMate Language](#reference). There is no
+separate security layer: a concept is an ordinary element that carries a **type** (a specialization, the paper's
+"stereotype") plus profile annotations. The type is a filterable annotation, so views, queries and lists can group by it.
+
+| Security concept | Kind | Type annotation | Notes |
+|------------------|------|-----------------|-------|
+| Threat (circumstance) | `MotivationDriver` | `driver/type: threat` | also opportunity, regulation, market |
+| Threat agent | `BusinessActor`, `ApplicationComponent`, `TechnologyNode` | none | the `causedBy` of an event |
+| Threat event | `BusinessEvent`, `ApplicationEvent`, `TechnologyEvent` | `event/type: threat-event` or `attack` | `attack` = intentional |
+| Loss event, incident | the three event kinds | `event/type: loss-event` or `incident` | the layer says where it happens |
+| Risk | `MotivationAssessment` | `assessment/type: risk` | initial and residual profile, `risk/treatment` |
+| Vulnerability | `MotivationAssessment` | `assessment/type: vulnerability` | `assesses` the assets it is found on |
+| Control objective | `MotivationGoal` | `goal/type: control-objective` | the risk is `mitigatedBy` it |
+| Control measure | `MotivationRequirement` | `requirement/type: control-measure` | a goal `realizes` it; the risk can be `mitigatedBy` it |
+| Control implementation | `BusinessControl`, applications, nodes, processes | none | `satisfies` / `realizes` the measure |
+| Proof of the control | `ComplianceEvidence` | `evidence/type` | `evidence/status: not-applicable` where the requirement does not apply |
+| Asset at risk | any application, technology, data or process kind | `asset/value`, `asset/confidentiality`, `asset/integrity`, `asset/availability` | the protection need (BSI Schutzbedarf) |
+| Policy (design level) | `MotivationPrinciple` | `principle/type: security-policy` or `risk-policy` | status, validity, framework mapping |
+| Operational policy, regulation | `MotivationConstraint` | none | the paper has no element for operational policy |
+| Risk domain | none; annotation `risk/domain` | `risk/domain`, `risk/category` | group by it with a query or a `View` |
+
+The chain, as in the paper's Coldhard Steel example:
+
+```
+MotivationDriver (threat) ──influences──→ MotivationAssessment (risk) ──mitigatedBy──→ MotivationGoal (control objective)
+        │ triggers                                  │ assesses                                      │ realizes
+        ↓                                           ↓                                               ↓
+BusinessEvent (loss event) ←──influences── MotivationAssessment (vulnerability)      MotivationRequirement (control measure)
+        ↑ triggers                                                                                  ↑ satisfies / realizes
+TechnologyEvent / ApplicationEvent (threat event, attack)                         BusinessControl / asset ──evidencedBy──→ ComplianceEvidence
+```
+
+```yaml
+kind: MotivationDriver
+metadata: { name: Threat:Intrusion, annotations: { driver/type: threat } }
+spec:
+  influences: { motivationAssessments: [Risk:Intrusion] }
+  triggers:   { businessEvents: [Loss:DataLeak] }
+---
+kind: MotivationAssessment
+metadata:
+  name: Risk:Intrusion
+  annotations:
+    assessment/type: risk
+    risk/initial-likelihood: high
+    risk/residual-likelihood: low
+    risk/treatment: mitigate
+    risk/domain: customer-data
+spec:
+  ownedBy: { businessRoles: [Role:RiskOwner] }
+  assesses: { technologyNodes: [Node:Web1] }
+  mitigatedBy: { goals: [Objective:ReduceExposure], businessControls: [Control:FirewallReview] }
+---
+kind: MotivationGoal
+metadata: { name: Objective:ReduceExposure, annotations: { goal/type: control-objective } }
+spec:
+  realizes: { motivationRequirements: [Measure:Firewall] }
+---
+kind: MotivationRequirement
+metadata: { name: Measure:Firewall, annotations: { requirement/type: control-measure } }
+spec: {}
+---
+kind: BusinessControl
+metadata: { name: Control:FirewallReview }
+spec:
+  ownedBy: { businessRoles: [Role:ControlOwner] }
+  satisfies: { motivationRequirements: [Measure:Firewall] }
+```
+
+How to model it:
+
+- **Events and their types.** A threat event `triggers` a loss event; the three event kinds (business, application,
+  technology) say on which level it happens and a technology event may trigger an application or business event. Use
+  `event/type` to tell threat events, attacks, loss events, incidents, opportunity events, audits, scans and changes apart.
+- **Vulnerability scan.** One `MotivationAssessment` of type `vulnerability` per finding, `assesses` every node it was
+  found on, `influences` the loss events and risks it makes possible. Business impact follows from the model: the node
+  serves services, services serve processes.
+- **Grouping (risk domains).** ArchiMate has no domain element; set `risk/domain` (and `risk/category`: hazard,
+  financial, operational, strategic, compliance, security) on events, assessments, drivers, requirements, controls and
+  assets, and query or build a `View` per domain to see its threats, risks, measures and assets together.
+- **Policies.** The text of a policy is a `Page`; the structured statement (owner, validity, status, framework) is a
+  `MotivationPrinciple` that links to the page with `[[Page]]`.
+- **Initial and residual risk.** Record both on the assessment (`risk/initial-*`, `risk/residual-*`) and the decision
+  in `risk/treatment`.
+
+<a id="reference"></a>
+**Reference:** Band, Engelsman, Feltus, González Paredes, Hietala, Jonkers, Massart,
+[Modeling Enterprise Risk Management and Security with the ArchiMate Language](https://pure.unamur.be/ws/files/12366722/Modeling_Enterprise_Risk_Management_and_Secutity_with_the_ArchiMate_Language.pdf),
+The Open Group white paper (ArchiMate 2.1). For the NIST OSCAL vocabulary used for names of assessment and evidence
+fields see [OSCAL](https://pages.nist.gov/OSCAL/learn/concepts/layer/).
+
 ### Compliance Chain
 
 Shows how requirements are satisfied:
 
 ```
-BusinessRequirement
+MotivationRequirement
        ↑ satisfies
 ComplianceEvidence
        ↑ evidencedBy
@@ -151,6 +350,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 +431,7 @@ relations:
 ### Compliance Mapping
 
 ```yaml
-kind: BusinessRequirement
+kind: MotivationRequirement
 name: DataEncryption
 annotations:
   requirement/reference: c5-2020, gdpr-2018
@@ -204,3 +441,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

@@ -122,7 +122,14 @@ The metamodel defines architectural entities and their relationships across all
 
 **Cross-Cutting:**
 
-- **Principle**, **Constraint**, **Requirement**, **Gap**, **Work Package**, **Location**
+- **Principle**, **Constraint**, **Requirement**, **Location**
+- **Gap**, **Work Package**, **Deliverable**, **Plateau**, **Implementation Event**: the Implementation & Migration layer (`ImplementationGap`, `ImplementationWorkPackage`, `ImplementationDeliverable`, `ImplementationPlateau`, `ImplementationEvent`)
+
+**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`
+
+**Risk and security:** the Open Group overlay (*Modeling Enterprise Risk Management and Security with the ArchiMate Language*) maps threats to **Driver** (`MotivationDriver`), threat and loss events to **Business/Application/Technology Event**, risks and vulnerabilities to **Assessment** (`MotivationAssessment`), control objectives to **Goal**, control measures to **Requirement** and policies to **Principle** (`MotivationPrinciple`), each with a type annotation. See [Modeling Guide](modeling.md#security-and-risk). How relations are directed (top-down, DAG) is described under [Direction of Relations](modeling.md#direction-of-relations).
 
 ### Critical Relationships
 

data/lib/archsight/annotations/asset_annotations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Asset module adds the asset profile of an asset at risk: its value and its protection need (BSI "Schutzbedarf")
+module Archsight::Annotations::Asset
+  NEED = %w[normal high very-high].freeze
+
+  def self.included(base)
+    base.class_eval do
+      annotation "asset/value",
+                 description: "Value of the asset to the organization",
+                 title: "Asset value",
+                 enum: %w[low medium high critical],
+                 filter: :word
+
+      annotation "asset/confidentiality",
+                 description: "Protection need for confidentiality",
+                 title: "Confidentiality need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+
+      annotation "asset/integrity",
+                 description: "Protection need for integrity",
+                 title: "Integrity need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+
+      annotation "asset/availability",
+                 description: "Protection need for availability",
+                 title: "Availability need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+    end
+  end
+end