Nuances: impact and about:

What could surprise you here, why it is so, and what to do. Each entry has a level, 1 (day one) to 5 (expert): the index lists them all by level.

ductus impact only knows what's named (level 2)

• What: it finds interfaces through about: (applications, vendors, sender hosts), destinations' application/vendor, the resources.yaml entries they use, and the databases and APIs their code names. A side with no system named is invisible to --vendor and --application. Host names are compared as written unless you pass --resolve (DNS lookups, from where you run it).
• What to do: fill in about: when creating an interface (ductus new writes it); validate warns about gaps, and require_about: true in ductus.yaml makes them errors. Name the vendor on shared resources once in resources.yaml. List senders' subnets in about.from.hosts: the engine can't know where inbound connections come from.

A destination's owner is its interface's unless it says otherwise (level 1)

• What: about.owner owns the interface and every destination; owner: on a destination overrides it for that destination only (e.g. its code is another team's). ductus owners lists destinations separately only when their owner differs. ductus owners reassign --from A --to B changes only owner: values that are written down: a destination that inherits moves with its interface.
• What to do: to hand one destination to someone else, add owner: to it by hand; to split a person's interfaces, run reassign once per group with --interface. It edits interface.yaml in place (comments and layout kept), so commit and deploy the change like any other.

Moving ownership in the web UI is a preview, not a change (level 1)

• What: the Owners screen (and POST /owners/reassign/preview) shows what would change and gives a patch and the ductus owners reassign command; it writes nothing. The engine never edits its own project: interface.yaml lives in your repository, and a change made on the server would be undone by the next deploy. Owners shown stay as they are until the change is deployed.
• What to do: apply the patch in the project's repository (git apply owners.patch) or run the command there, review, commit and deploy. The preview reads the files on the engine's server, so preview against the engine running the version you'll change. The patch keeps each file's own line endings, which is what git apply needs: from an engine on Windows (CRLF files, Git for Windows's core.autocrlf) it applies to a Windows checkout; a patch made on Linux (LF) applies to a Linux checkout or one with autocrlf off.

An owner is a person when the text names exactly one account (level 1)

• What: an owner: is free text. The engine matches it to an account ignoring case and surrounding spaces: a username first, then an email, then a display name; the first of those that matches anyone decides. At that level one enabled account wins over any number of disabled ones (a person given a new account keeps their email; the old one, refused, doesn't make it ambiguous); two enabled ones (two "Anna Smith"s) name nobody: no link, no alert mail to either (a guess would send one person's alerts to the other); only disabled ones name that account, flagged: its person probably left, and alerts go nowhere for it (not even to the text, when it is an email: their old mailbox; since 0.6.7.3). When no account has the text now, the names accounts had before are tried the same way (since 0.6.7 every change of a username, display name or email keeps the old value, whoever made it: an admin, or the directory at a sign-in or refresh): the one account that had it is the owner, shown as renamed ("this was their display name until 2026-03-02"), and alerts go to its email now. When an account has the text now and another had it before, the one that has it now is the owner (the current names always decide first), shown as reused: the text may have been written for the earlier person. Both are warnings (⚠): the owner still reaches a person. An owner that is an account shows as that person (name, email) on the Owners and interface pages, makes the interface theirs under Interfaces → Mine, and gets to: owner alerts. Otherwise it is a team in owners: (ductus.yaml; a team wins over an account's former name), an email address, or nobody. With a directory, an email address of someone in a Ductus group becomes their account (see Directory owners get their account when they're in a Ductus group). Renames before 0.6.7 aren't known (no old values were kept then): such an owner reads as nobody until fixed once. ductus owners with DUCTUS_DATABASE_URL marks each owner, ductus validate does too when it has the database, the Owners page says the same, and the engine logs at start the owners it can't reach and those it reaches by a former name.
• What to do: write owners as email addresses (unique; a display name may not be, and both get renamed). An owner written another way that names an account is warned with the email to write ("write their email: olaf@…"), and renamed and reused owners with the exact fix: ductus owners --check prints ductus owners reassign --from '<text>' --to <email> under each and still passes (exit 0); the Owners page's Update opens that move, previewed. For a reused one, decide who is meant first: the fix offered is the one alerts reach now, the warning names the earlier one's email too. Name teams and mailing lists in owners:. Run ductus owners --check in the pipeline that deploys the project (it fails on an owner that reaches nobody, a disabled account, or one that names several). When someone leaves, move what they own with ductus owners reassign before disabling them.

Moving an owner moves their resources.yaml entries too (level 2)

• What: ductus owners reassign --from A --to B (and the Owners page's preview) changes owner: A in every interface.yaml and in resources.yaml (databases, APIs, SFTP servers, directories), so certificate alerts follow the person. Naming --interface x or --resource y moves only what is named (naming interfaces leaves resources.yaml as it is). The preview says when the new owner isn't an account.
• What to do: to split someone's work, run it per group with --interface/--resource (or untick on the Owners page). Commit the resources.yaml change with the interface files.

Operators start on their own interfaces (level 1)

• What: Interfaces opens on "Mine" for an operator who owns at least one interface (or a destination of one); everyone else, and an operator who owns nothing, starts on All. "Mine" goes by the owner matching above, for the person signed in (a token acts for its owner; a service token has no "Mine"). The choice is in the address (?mine=false), so a bookmark keeps it.
• What to do: nothing; if an operator sees an empty "Mine", their owner texts don't name their account (see above).

Your own documentation fields are checked by ductus validate, not by the engine (level 2)

• What: docs-schema.yaml declares the fields your company wants on every interface, destination or resources.yaml entry (text, enum, date, url, person, list; required or not; where each applies); the values go in a flat custom: block beside the other keys (not under about:). A missing required value, a value outside an enum, a date that isn't YYYY-MM-DD, an undeclared name or a field used where it doesn't apply is an error in ductus validate (and ductus docs --missing exits 1) — but the engine starts anyway and shows what is there. Documentation must never be the reason a hospital's interfaces are down. In the web UI a missing required value reads "Missing"; a broken docs-schema.yaml is logged at startup and the fields are ignored until it is fixed. Enums match exactly, case included (yes is not Yes): that is the point, since it stops "Yes/yes/Y" from drifting into your reports.
• What to do: put ductus validate in the pipeline that deploys the project, so a gap is caught before the engine sees it. Declare a field you can't fill in yet as required: false first, then tighten it. Quote "yes" and "no" values in YAML so no tool reads them as booleans (the engine takes them as text).

The documentation snapshot is as old as the last engine start (level 3)

• What: at every start the engine writes each interface's and resource's documentation as JSON, in your field names, to the docs_snapshot table, so reports and BI tools can ask docs->'custom'->>'baa_signed' = 'no' in SQL. The YAML in Git stays the source of truth: the table is made to match the project at start (entries you removed disappear) and is not updated while the engine runs. There is no history yet (it comes with versioned releases). The web UI and API read the files as loaded at start too: editing custom: on a running engine shows after a restart.
• What to do: deploy documentation changes like any other (restart or roll the engine); don't edit docs_snapshot by hand, it is rewritten. Several engines on one database each write their own project's rows, the last to start wins: give each project its own database, as you already do.