archsight 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47bed92ae99f141a261c0dc19a47095a566bd60b9c6a9201dbcd2f6298e1a35f
-  data.tar.gz: 5ff9e1d7d7f02162192a95d86a3a89194b1e450006f4766191da9206f7de55bf
+  metadata.gz: 464d36ecbae64b55e25554f9d60d9c208fb2477ba1910f2318c415eef2cea018
+  data.tar.gz: e423de1798a1a0fc99f16220051139800780e6bd9f01b096bce378dda1ccb25e
 SHA512:
-  metadata.gz: dd5b2c1db012e147af1f123c530184b1c4a6eab3b5e7e1e1dbacb658c6e70080b461975d659d68faeca43118989d52d63d134a91fee79767966f06797e352b3c
-  data.tar.gz: f50137692088c6f3a24e799eb7433206e5124c5d83805b94e4d1ea1992537b71528f742538fe6362f4c56c547ffa88cca3d5719bfa153fb09181b893046f4de5
+  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,17 +91,22 @@ 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
 - `analyze_resource` - Get detailed resource information and impact analysis
 - `resource_doc` - Get documentation for resource kinds
 
-**Export to Confluence**: `archsight export --to confluence` publishes pages to the Confluence page they link to, with images, diagrams and draw.io, and refuses to overwrite edits made in Confluence unless `--force` ([Wiki pages](docs/pages.md#exporting-to-confluence)).
+**Export to Confluence**: `archsight export --to confluence` publishes pages to the Confluence page they link to, with images, diagrams and draw.io, views and requirements as tables, and refuses to overwrite edits made in Confluence unless `--force` ([Wiki pages](docs/pages.md#exporting-to-confluence)).
 
 **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)).
+**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/computed_annotations.md

@@ -40,9 +40,13 @@ Computed annotations support all the same options as regular annotations:
 | `enum` | Array | nil | Allowed values |
 | `sidebar` | Boolean | false | Show in sidebar |
 | `type` | Class | nil | Type for value coercion (Integer, Float, String) |
-| `list` | Boolean | false | Whether values are lists |
+| `summary` | Boolean | false | Return the value with every search hit of this kind (at most 3 per kind) |
 | `&block` | Block | required | The computation logic |
 
+`summary: true` (also available on regular `annotation` definitions) marks the value as a summary attribute: the
+search API returns it with every hit of the kind (`highlights`) and the result page shows it next to the name.
+A kind can have at most 3 summary annotations; a fourth raises an `ArgumentError` when the kind is defined.
+
 ### Value Handling
 
 - **Nil values**: Not stored (annotation key won't exist)
@@ -89,8 +93,7 @@ end
 computed_annotation 'computed/languages',
                     title: 'Languages',
                     description: 'All programming languages used',
-                    filter: :list,
-                    list: true do
+                    filter: :list do
   collect(outgoing_transitive(:TechnologyArtifact), 'scc/languages')
 end
 ```
@@ -299,8 +302,7 @@ class ApplicationComponent < Base
   computed_annotation 'computed/languages',
                       title: 'Languages',
                       description: 'All programming languages used across related artifacts',
-                      filter: :list,
-                      list: true do
+                      filter: :list do
     collect(outgoing_transitive(:TechnologyArtifact), 'scc/languages')
   end
 

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/licenses.md

@@ -236,8 +236,7 @@ end
 # Collect all unique dependency licenses across the portfolio
 computed_annotation 'computed/license_types',
                     title: 'All License Types',
-                    filter: :list,
-                    list: true do
+                    filter: :list do
   collect(outgoing_transitive(:TechnologyArtifact), 'license/dependencies/licenses')
 end
 

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,17 +138,110 @@ 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
-ApplicationService
+ApplicationService (or TechnologyService / TechnologySystemSoftware)
+```
+
+Technology elements such as a Kubernetes cluster runtime can plan, realize and be evidenced
+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
 
@@ -190,7 +286,7 @@ relations:
 ### Compliance Mapping
 
 ```yaml
-kind: BusinessRequirement
+kind: MotivationRequirement
 name: DataEncryption
 annotations:
   requirement/reference: c5-2020, gdpr-2018
@@ -200,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

@@ -146,6 +146,62 @@ link to the resource. Other kinds are not embeddable; an unknown name, another k
 a sentence (instead of on its own line) is shown as a marker or a link, and `archsight lint` reports embeds that do not
 resolve. Code blocks and inline code are left alone.
 
+### Inline views
+
+A view that only this page needs does not have to be a resource of its own: a fenced ```` ```view ```` block holds the
+View as it would be written in a YAML file and is shown like an embedded view:
+
+````markdown
+```view
+apiVersion: architecture/v1alpha1
+kind: View
+metadata:
+  name: Services without backup      # the title above the list, optional
+  annotations:
+    view/query: 'ApplicationService: backup/mode == "none"'
+    view/fields: name, @owner
+    view/sort: -name
+    view/type: list:name
+```
+````
+
+Only `view/query` is required; `kind`, if given, must be `View` and `apiVersion` can be left out. Other annotations are
+ignored, so a View's YAML can be pasted in unchanged (to turn the block into a real view later, or the other way round).
+It loads and runs in the browser like any embed; the server only writes `<div class="view-embed" data-title data-query
+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.
+
+### Requirements of a selection of resources
+
+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 "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
+```
+````
+
+The table has one row per requirement of all selected resources. Its status is the best one any of them gives it
+(`realizes` = implemented, then `partially`, then `plans` = planned), and a "Realized by" column names the resources with their own
+status (left out when only one resource is selected). Rows are sorted by priority, then name; `priority` and `status` filter the rows.
+Like views, the block is only a placeholder on the server (`<div class="requirements-embed" data-title data-of data-priority
+data-status>` around the source): the frontend loads the rows from `GET /api/v1/requirements?of=&priority=&status=`, so rendering a page
+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
@@ -202,6 +258,8 @@ If several pages qualify, a page named `home` wins over one that is only titled
 - Tables, code blocks and other GitHub-flavoured markdown.
 - Diagrams: fenced ```` ```asd ```` blocks (see [Diagrams](/doc/diagram)) replace draw.io drawings.
 - Links: `[[Page title]]`, `[[page-name]]`, `[[Name|label]]` and `[[Kind/Name]]` link to pages and resources.
+  A link without a label shows the title of a page and the name of a resource (`[[ApplicationComponent/KubeVirt]]` shows "KubeVirt"); hovering it shows the
+  kind and the first line of the description (the status of a page). The export to Confluence writes the same texts, without the hover.
 
 ## Editing
 
@@ -224,6 +282,7 @@ or `.../display/KEY/Title`). Without `PAGE` every page that has a `confluence:`
 
 ```bash
 archsight export --to confluence -r resources                 # all linked pages
+archsight export --to confluence -r resources --tag public    # only pages tagged `public` (repeat or list: any match)
 archsight export --to confluence handbook-home --dry-run      # show what would happen
 archsight export --to confluence handbook-home --force        # overwrite changes made in Confluence
 ```
@@ -257,10 +316,17 @@ confluence:
 With `drawio` off nothing draw.io-specific is written, so any Confluence shows the diagrams. Rendering a `.drawio` needs the
 draw.io desktop CLI (`drawio`, or `ARCHSIGHT_DRAWIO_CLI`) on the machine that exports; the preview of an SVG needs
 `rsvg-convert` or that CLI. A diagram that cannot be rendered fails the page instead of leaving a blank diagram. Attachments an
-earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` to pages that have a Confluence link
-become links to them, other links are plain text; embedded views and analyses (`![[View/..]]`) become a note, their content
-is live and exists in Archsight only. A page with a broken image or a diagram that does not render is not exported and
-reported as failed. The Confluence title is kept.
+earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
+become links to them, other links to Archsight (pages without a Confluence link, resources, searches) are plain text. A page with a broken image, a diagram that does not render or an invalid
+```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own.
+
+**Views and requirements** are live in Archsight, so Confluence gets a regular table with the data of the moment of the export (every
+export writes the current data; a page whose tables did not change is `unchanged`): `![[View/Name]]` on a line of its own, a
+```` ```view ```` block and a ```` ```requirements ```` block each become a table with the title and item count above it, the columns of
+the view (Name, Kind unless `list:name`, the `view/fields`, sorted by `view/sort`; times are the stored values, not "3 days ago") or
+the requirements table (status and priority as status lozenges: implemented green, partial yellow, planned blue; `must` red,
+`should` yellow, `may` grey), and names of pages that have a Confluence link as links. At most 200 rows are exported, a note says how many
+were left out. A `![[View/..]]` that is not alone on its line or names no view stays a note, and so does `![[Analysis/..]]` (it runs a script).
 
 **Links in diagrams**: a node with `resource "Some Page"` links to the Confluence page of that wiki page (the page's own
 `confluence:` link) instead of its Archsight address, which means nothing in Confluence. A reference to a page without a
@@ -276,8 +342,8 @@ changed it and when, and the command exits with 1. `--force` overwrites it anywa
 were replaced. A page whose generated content is unchanged is left alone (no new version).
 
 **Locking and revisions**: unless `--no-lock`, editing is restricted to the exporting user (if the server does not allow it,
-the export still succeeds and says "NOT locked"). Every exported version has the message "Generated by Archsight <version> from
-<file>, do not edit in Confluence", and the page starts with a note that it is generated and that the source file is the place
+the export still succeeds and says "NOT locked"). Every exported version has the message "Generated by Archsight `<version>` from
+`<file>`, do not edit in Confluence", and the page starts with a note that it is generated and that the source file is the place
 to edit.
 
 ## Pages and AI assistants (MCP)

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:
 
@@ -263,3 +270,20 @@ Using `in` to simplify OR conditions:
 
     # Combined with other conditions:
     activity/status == "active" & repository/artifacts in ("container", "chart")
+
+## Search results
+
+The result page lists the hits with a count per kind. Click a kind to narrow the list; the query stays the same.
+Every hit also shows its **summary attributes**: up to three annotations per kind (normal or computed) that
+the kind definition marks with `summary: true`, for example the activity status of a repository or the priority
+of a requirement. Clicking a tag value searches for that value.
+
+The same data is available from the API: `GET /api/v1/search?q=...` returns `by_kind` (hits per kind, for all
+hits of the query) and, for each hit, `highlights`:
+
+    "highlights": [
+      { "key": "activity/status", "title": "Activity Status", "value": "active", "format": "tag_word", "type": null }
+    ]
+
+Add `kind=TechnologyArtifact` to narrow the hits to one kind (`total` and paging follow, `by_kind` still counts
+all hits).

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/annotation.rb

@@ -5,7 +5,7 @@ require_relative "person"
 
 # Annotation represents a single annotation definition with its schema and behavior
 class Archsight::Annotations::Annotation
-  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :list, :editor
+  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :summary, :editor
 
   def initialize(key, options = {})
     @key = key
@@ -15,7 +15,7 @@ class Archsight::Annotations::Annotation
     @enum = options[:enum]
     @validator = options[:validator]
     @sidebar = options.fetch(:sidebar, true)
-    @list = options.fetch(:list, false)
+    @summary = options.fetch(:summary, false)
     @editor = options.fetch(:editor, true)
     @type = options[:type]
 
@@ -51,8 +51,9 @@ class Archsight::Annotations::Annotation
     @filter == :list
   end
 
-  def list_display?
-    @list == true
+  # Summary annotations are returned with every search hit (at most MAX_SUMMARY per kind)
+  def summary?
+    @summary == true
   end
 
   def has_validation?

data/lib/archsight/annotations/computed.rb

@@ -28,7 +28,7 @@ class Archsight::Annotations::ComputedEvaluator
     @instance = instance
     @database = database
     @manager = manager
-    @resolver = Archsight::Annotations::ComputedRelationResolver.new(instance, database)
+    @resolver = Archsight::Annotations::ComputedRelationResolver.new(instance, database, manager.traversal_cache)
   end
 
   # Access a regular annotation value from the current instance
@@ -170,8 +170,12 @@ end
 # ComputedManager orchestrates the computation of all computed annotations.
 # It handles lazy evaluation, caching, and cycle detection.
 class Archsight::Annotations::ComputedManager
+  # Shared by all resolvers of this run, see ComputedRelationResolver::TraversalCache
+  attr_reader :traversal_cache
+
   def initialize(database)
     @database = database
+    @traversal_cache = Archsight::Annotations::ComputedRelationResolver::TraversalCache.new(database)
     @computed_cache = {}  # { [instance_object_id, key] => value }
     @computing = Set.new  # For cycle detection
   end