Skip to content
LQMS
Administering an LQMS Installation
Initializing search
nburri/lqms
LQMS
nburri/lqms
Home
Evaluate LQMS
Evaluate LQMS
LQMS Known Limits
LQMS Security Posture
Architecture
Architecture
1. Introduction and Goals
2. Architecture Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Crosscutting Concepts
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary
The arrival bundle format
Decisions (ADRs)
Decisions (ADRs)
ADR-0001: Content-Addressed Document Storage with PostgreSQL as Source of Truth
ADR-0002: Single Instance with Scope Hierarchy and Copy-on-Derive
ADR-0003: Fixed Life Cycle States with Configurable Review Processes
ADR-0004: Global Catalogs for Roles and Document Types with Per-Scope Activation
ADR-0005: Modular Monolith
ADR-0006: Three-Layer Search with In-Database Index and Pluggable LLM
ADR-0007: Angular Frontend with Server-Side-Only Enforcement
ADR-0008: Flyway Migrations and jOOQ Codegen from the Migrated Schema
ADR-0009: RLS Enforcement via a Session-Scoped Authorized Scope Set
ADR-0010: Self-Managed QMS via an Internal Mandator
ADR-0011: Authentication via OIDC SSO with Server-Side (BFF) Sessions
ADR-0012: Permission-Based Authorization and System Bootstrap
ADR-0013: User Identity Lifecycle
ADR-0014: Electronic Signatures (Part 11 / Annex 11-Capable)
ADR-0015: Document Effectivity, Periodic Review & Validity
ADR-0016: Data Retention, Disposal & Privacy (FADP / GDPR)
ADR-0017: Multi-Part Version Content
ADR-0018: Non-Functional Targets (Capacity, Availability, Security)
ADR-0019: Notifications & Tasks
ADR-0020: Internationalization (Content Language, Time Zones, Formatting)
ADR-0021: General Typed Document Relationships
ADR-0022: Read-Acknowledgement & Questionnaires
ADR-0023: Migration / Import — Current Released State
ADR-0024: Draft / In-Review Cancellation
ADR-0025: Disposal & Erasure Mechanics (Storage, Index, Backups)
ADR-0026: RLS Runtime Safety — Connection-Pool Scope Isolation
ADR-0027: RLS Boundary — Content-Plane vs Control-Plane
ADR-0028: Stateless Encrypted Token-State Cookie (no server-side session store)
ADR-0029: Document Content Model — Draft-Freeze, Content-Table RLS, Append-Only Audit
ADR-0030: Review & Life-Cycle Realization Model
ADR-0031: Released-base readability enforcement & copy-on-derive mechanics
ADR-0032: Frontend realization — Quinoa, Angular Material, i18n & E2E
ADR-0033: CSRF control for the BFF session — SameSite + JSON content-type
ADR-0034: Notification realization — in-process domain events + system-context fan-out
ADR-0035: Fan-out contract as shipped — gate semantics, count disclosure, audit protocol
ADR-0036: Repository layer — services carry rules, repositories carry jOOQ
ADR-0037: Task scheduler — in-process tick, advisory-lock election, SQL sweep
ADR-0038: Periodic-review realization — derived due date, policy-gated confirmation
ADR-0039: Sweep & periodic-review contract as shipped — grants, guards, addressing
ADR-0040: Disposal-due surfacing — closure-anchored retention, scope-level legal hold
ADR-0041: Email channel & notification i18n — notification-as-outbox, structured messages
ADR-0042: Disposal execution — document tombstoning, single-actor hard-gated destruction
ADR-0043: Disposal blob deletion is post-commit, GC-backstopped
ADR-0044: Search FTS baseline — event-indexed, RLS-scoped search_index
ADR-0045: Image Attachments as Content Parts (Rich-Content Slice R2)
ADR-0046: Four-Eyes — Submitter Excluded from Approval
ADR-0047: Four-Eyes — Submitter-Only Exclusion
ADR-0048: Document Organization — Folder Tree per Scope
ADR-0049: Content Model Round 2 — Type Categories, Template Instantiation, Trace Relations, Completeness Rules
ADR-0050: Live Frontend — SSE State Push, CodeMirror 6, Draft Presence
ADR-0051: In-Text Document Links (doc: Scheme)
ADR-0052: Addressees & Read-Acknowledgement (REQ-TRN Realization)
ADR-0053: Addressees Per Document + Process Owner (amends ADR-0052 K-1)
ADR-0054: Process Owner Is a Role (amends ADR-0053 P-3)
ADR-0055: WYSIWYG Editing Mode over Markdown (editor step R4)
ADR-0056: Visual-Editor Chrome via Milkdown Crepe (gated adoption)
ADR-0057: Content Record Is the ProseMirror Document Tree; Markdown Becomes a Derived Projection
ADR-0058: PM_DOC Is the Only Content Format (pre-production cut; amends ADR-0057 §5)
ADR-0059: Editor Engine Switches to TipTap (spike-gated; supersedes the Milkdown/Crepe choice)
ADR-0060: Backup & Restore — Scripted Ordered Backup with Automated Restore Rehearsal
ADR-0061: CSV — Generated Validation Package per Release
ADR-0062: SBOM — CycloneDX over the Production Layers, Validated Against the Artifact
ADR-0063: User Identity Binds on Subject Only (Issuer Becomes Provenance)
ADR-0064: Per-Document Workflow Role Bindings (Author / Reviewer / Releaser), Enforced
ADR-0065: Diagrams — Excalidraw as the Manual Layer, Mermaid Stays for Text-First/UML
ADR-0066: WITHDRAW — the Author Side May Reclaim a Version from Review
ADR-0067: Review Comments — Anchored, Immutable, Resolvable
ADR-0068: Confluence/Jira QMS Import — Staged, Read-Only, Repeatable
ADR-0069: Arbitrary File Attachments — Download-Only Confinement
ADR-0070: Training Questionnaires — Versioned, Auto-Scored, Release-Gated
ADR-0071: Training Plans — Document Obligations + External Trainings & Certifications
ADR-0072: Diagrams — Self-Hosted draw.io Replaces Excalidraw
ADR-0073: Per-Scope QMS Configuration Surface
ADR-0074: PDF Export of Released Documents — Server-Side via Apache FOP over the Canonical Projection
ADR-0075: Source History Import — Continuity Without Forged Audit
ADR-0076: Periodic-review status visibility (completing MVP gap #2)
ADR-0077: Requirement Items — Keyed Blocks Inside Controlled Documents
ADR-0078: Generalized Trace Items (Traceability Model — Stage A)
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views
ADR-0081: Draft-Only Trace-Structure Changes, Server-Enforced
ADR-0082: Table-Shaped Risk Authoring over Risk Blocks
ADR-0083: The TD Dossier — a Versioned, Cross-Scope, Regulatory-Structured Deliverable
ADR-0084: Validation & Regulatory Axes (Traceability Model — Stage C)
ADR-0085: Relation-Layer Consolidation — One Trace Vocabulary, One Surface
ADR-0086: Requirement Traceability Chains — End-to-End Path View + Flat Path Export
ADR-0087: The Scope Traceability Report — One Derived Overview Artifact, Never a Controlled Document
ADR-0088: Verification Evidence Classes — Planned vs. Verified, Derived at the Read Layer
ADR-0089: Recurring Obligations — Periodic Tasks With Record Evidence, Not Calendar Series
ADR-0090: Release & Versioning Policy — Deliberate Releases, One Auditor-Facing Number
ADR-0091: Release Modes — Single-Person Record Release With a Structural Four-Eyes Floor
ADR-0092: Orphan-Blob Garbage Collection With a Quarantine Bin
ADR-0093: One Scope Context — the Toolbar Switcher Is the Only Scope Selector
ADR-0094: Calendar-Anchored Obligation Schedules (Clamped, Never Too Late)
ADR-0095: Key-Rule Governance — Free Until First Use, Then Frozen
ADR-0096: Transition Permissions — Always Visible, Deny Unless Granted
ADR-0097: A Governed Provisioning Surface — MANAGE_SCOPES
ADR-0098: Org Chart × Role System — Marriage at the Evidence Level, Never in Authorization
ADR-0099: The User Manual is an In-App Topic Reference, Not a Document
ADR-0100: LQMS Is the Living Quality Management System
ADR-0101: The Executable Validation Journey (PQ Evidence That Cannot Drift)
ADR-0102: Typed Template Variables (text | date | number — and Deliberately No Enum)
ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
ADR-0105: Navigation Information Architecture — Group by Moment-of-Use
ADR-0106: The Client Reflection Follows Assignments, Not Only Content Reach
ADR-0107: The Audit Append Gate Follows Assignment Reach, Not Content Reach
ADR-0108: Mandator Membership — Invite-Accept, with Pre-Assigned Responsibilities
ADR-0109: Organization Founding Is Its Own Process
ADR-0110: The Audit Trail Is Not a Read Model
ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines
ADR-0112: The Element-Kind Catalog — Semantics in the Model, Not Only in the Code
ADR-0113: Project Arrival Import — Records Arrive as They Are, People Arrive as They Were
ADR-0114: The Operating Model Arrives — Roles as Functions, Names as Words, People as This Instance's Decision
ADR-0115: Collaborative Draft Editing — Two Carets, One Truth, Honest Credit
ADR-0116: The System Maintenance Surface — the App Backs Itself Up, the Host Keeps One Dumb Job
ADR-0117: Role Documentation — a Link, a Finding, Per-Source Recognizers; Substitution Rejected
ADR-0118: The Offline QMS Copy — the Repo Carries the Audit Pack, Not a Second Renderer
ADR-0119: Module-Internal Package Structure — Capabilities First, Layers Second, the Root Is the Surface
ADR-0120: The Shared Kernel — the Domain-Exception Vocabulary Leaves the Authorization Module
ADR-0121: The Project Administrator Role — Per-Scope Administration With Read Access, Seeded in the Base Catalog
ADR-0122: Organization-Level Administration — the Cascade Stays, Becomes Visible, and Founds Projects
ADR-0123: Draft Save-Points — Every Save Restorable, Kept for the Life of the Version
ADR-0124: The Birth Path Completes Without Borrowing Content Clothes
ADR-0125: The Export Twin — Export Emits an Arrival Bundle
ADR-0126: Project Dissolution — the Un-Birth of an Unused Scope
ADR-0127: The Base-QMS Layers — One Library, Derived Adaptations, Local Records
ADR-0128: The GLOBAL Cascade Carries Administration, Never Content
ADR-0129: Role Identity from a GLOBAL Assignment Acts in GLOBAL Alone
ADR-0130: Break-Glass — the Project Administrator's Escalation Is a First-Class, Witnessed, Self-Expiring Act
ADR-0131: Role Substitution as Declared Adoption Edges — Emergency Cover Is Governed, Own-Name, Timed Staffing
ADR-0132: Dual-Hat Reviewer Satisfaction Is a Declared Policy Choice — the Strict Floor Stays the Default
ADR-NNNN:
</span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <div class="md-nav__link md-nav__container"> <a href="../../requirements/" class="md-nav__link "> <span class="md-ellipsis"> Requirements </span> </a> <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Requirements </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../requirements/stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_api_ui/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_audit_reporting/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_catalogs/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Catalogs, Roles & Users </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_data_protection/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Data Protection, Retention & Disposal </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_documents/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Documents, Versions & Storage </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_dossiers/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Technical Documentation Dossiers </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_effectivity/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Effectivity, Periodic Review & Validity </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_gspr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Regulatory Conformity (GSPR / Essential Principles) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Life Cycle & Reviews </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_memberships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Mandator Membership & Invitations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_risk/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Risk Management (ISO 14971 Hazards & Controls) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_sbom/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Software Bill of Materials & Supply-Chain Assurance </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_separation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Scopes, Mandators & Separation </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_training/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Read-Acknowledgement & Questionnaires </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_users/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: User Identity & Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_validation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Design Validation & the Validation Traceability Axis </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <div class="md-nav__link md-nav__container"> <a href="../../process/" class="md-nav__link "> <span class="md-ellipsis"> Process (IEC 62304) </span> </a> <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Process (IEC 62304) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../process/configuration_management_plan/" class="md-nav__link"> <span class="md-ellipsis"> Configuration Management Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/problem_resolution/" class="md-nav__link"> <span class="md-ellipsis"> Problem Resolution Process </span> </a> </li> <li class="md-nav__item"> <a href="../../process/risk_management/" class="md-nav__link"> <span class="md-ellipsis"> Risk Management </span> </a> </li> <li class="md-nav__item"> <a href="../../process/software_development_plan/" class="md-nav__link"> <span class="md-ellipsis"> Software Development Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/verification_plan/" class="md-nav__link"> <span class="md-ellipsis"> Verification Plan </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> <span class="md-ellipsis"> Operations </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Operations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../operations/genesis-installation/" class="md-nav__link"> <span class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Deployment Guide </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/server-deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <div class="md-nav__link md-nav__container"> <a href="../../traceability/" class="md-nav__link "> <span class="md-ellipsis"> Traceability </span> </a> <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Traceability </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../traceability/matrix/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Traceability Matrix </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <div class="md-nav__link md-nav__container"> <a href="../../validation/" class="md-nav__link "> <span class="md-ellipsis"> Validation (tool lane) </span> </a> <label class="md-nav__link " for="__nav_9" id="__nav_9_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> <span class="md-nav__icon md-icon"></span> Validation (tool lane) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../validation/templates/ai-authorship-posture/" class="md-nav__link"> <span class="md-ellipsis"> AI-Authorship Posture — How LQMS Is Built, and Why the Validation Evidence Does Not Rest on It (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/intended-use/" class="md-nav__link"> <span class="md-ellipsis"> Intended-Use Specification — LQMS as a QMS / Document-Control Tool (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/tool-risk-assessment/" class="md-nav__link"> <span class="md-ellipsis"> Tool-Risk Assessment — LQMS as a QMS Tool (TEMPLATE) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> <span class="md-ellipsis"> Regulatory </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Regulatory </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../regulatory/mdr-annex-i-skeleton/" class="md-nav__link"> <span class="md-ellipsis"> MDR Annex I — GSPR authoring skeleton (paraphrased) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" checked> <div class="md-nav__link md-nav__container"> <a href="../" class="md-nav__link "> <span class="md-ellipsis"> User guide </span> </a> <label class="md-nav__link " for="__nav_11" id="__nav_11_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_11"> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> <span class="md-ellipsis"> Administering an LQMS Installation </span> <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-the-three-altitudes" class="md-nav__link"> <span class="md-ellipsis"> 1. The three altitudes </span> </a> <nav class="md-nav" aria-label="1. The three altitudes"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#where-administration-lives" class="md-nav__link"> <span class="md-ellipsis"> Where administration lives </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#2-admin--content--the-boundary-is-a-witness-not-a-fence" class="md-nav__link"> <span class="md-ellipsis"> 2. Admin ≠ content — the boundary is a witness, not a fence </span> </a> <nav class="md-nav" aria-label="2. Admin ≠ content — the boundary is a witness, not a fence"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#what-a-project-administrator-holds-exactly" class="md-nav__link"> <span class="md-ellipsis"> What a project administrator holds, exactly </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-the-life-of-a-project-scope" class="md-nav__link"> <span class="md-ellipsis"> 3. The life of a project scope </span> </a> <nav class="md-nav" aria-label="3. The life of a project scope"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#31-birth" class="md-nav__link"> <span class="md-ellipsis"> 3.1 Birth </span> </a> </li> <li class="md-nav__item"> <a href="#32-staffing-and-the-operating-model" class="md-nav__link"> <span class="md-ellipsis"> 3.2 Staffing and the operating model </span> </a> </li> <li class="md-nav__item"> <a href="#33-dissolution" class="md-nav__link"> <span class="md-ellipsis"> 3.3 Dissolution </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-the-life-of-a-person" class="md-nav__link"> <span class="md-ellipsis"> 4. The life of a person </span> </a> <nav class="md-nav" aria-label="4. The life of a person"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-external-kind--people-who-are-not-accounts" class="md-nav__link"> <span class="md-ellipsis"> The EXTERNAL kind — people who are not accounts </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#5-role-administration-and-the-closure-lesson" class="md-nav__link"> <span class="md-ellipsis"> 5. Role administration, and the closure lesson </span> </a> <nav class="md-nav" aria-label="5. Role administration, and the closure lesson"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-three-seeded-roles" class="md-nav__link"> <span class="md-ellipsis"> The three seeded roles </span> </a> </li> <li class="md-nav__item"> <a href="#the-closure-lesson" class="md-nav__link"> <span class="md-ellipsis"> The closure lesson </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#6-what-the-system-tells-you-the-setup-check-and-the-dead-end-philosophy" class="md-nav__link"> <span class="md-ellipsis"> 6. What the system tells you: the setup check and the dead-end philosophy </span> </a> <nav class="md-nav" aria-label="6. What the system tells you: the setup check and the dead-end philosophy"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-philosophy-in-four-rules" class="md-nav__link"> <span class="md-ellipsis"> The philosophy, in four rules </span> </a> </li> <li class="md-nav__item"> <a href="#what-it-flags" class="md-nav__link"> <span class="md-ellipsis"> What it flags </span> </a> </li> <li class="md-nav__item"> <a href="#the-chip-monitors-the-wizard-remediates" class="md-nav__link"> <span class="md-ellipsis"> The chip monitors; the wizard remediates </span> </a> </li> <li class="md-nav__item"> <a href="#the-principle-behind-all-of-it" class="md-nav__link"> <span class="md-ellipsis"> The principle behind all of it </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#7-when-an-administrator-must-not-act" class="md-nav__link"> <span class="md-ellipsis"> 7. When an administrator must NOT act </span> </a> </li> <li class="md-nav__item"> <a href="#8-break-glass-and-emergency-cover" class="md-nav__link"> <span class="md-ellipsis"> 8. Break-glass and emergency cover </span> </a> </li> <li class="md-nav__item"> <a href="#9-troubleshooting--the-refusals-an-administrator-meets" class="md-nav__link"> <span class="md-ellipsis"> 9. Troubleshooting — the refusals an administrator meets </span> </a> <nav class="md-nav" aria-label="9. Troubleshooting — the refusals an administrator meets"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#permission-refusals" class="md-nav__link"> <span class="md-ellipsis"> Permission refusals </span> </a> </li> <li class="md-nav__item"> <a href="#the-refusals-an-administrator-actually-meets" class="md-nav__link"> <span class="md-ellipsis"> The refusals an administrator actually meets </span> </a> </li> <li class="md-nav__item"> <a href="#symptoms-that-are-not-refusals" class="md-nav__link"> <span class="md-ellipsis"> Symptoms that are not refusals </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#10-the-operators-half--where-installation-and-maintenance-live" class="md-nav__link"> <span class="md-ellipsis"> 10. The operator's half — where installation and maintenance live </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../project-context/" class="md-nav__link"> <span class="md-ellipsis"> The Project Context & App Version </span> </a> </li> <li class="md-nav__item"> <a href="../review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../topics/activity-trail/" class="md-nav__link"> <span class="md-ellipsis"> Who did what, when — reading a project's activity </span> </a> </li> <li class="md-nav__item"> <a href="../topics/admin-scopes/" class="md-nav__link"> <span class="md-ellipsis"> Renaming a project, and what can never change </span> </a> </li> <li class="md-nav__item"> <a href="../topics/authority-view/" class="md-nav__link"> <span class="md-ellipsis"> Who holds each function here, and what may it do </span> </a> </li> <li class="md-nav__item"> <a href="../topics/break-glass/" class="md-nav__link"> <span class="md-ellipsis"> The permission I need is held by a role I do not hold — what now? </span> </a> </li> <li class="md-nav__item"> <a href="../topics/coverage-and-chains/" class="md-nav__link"> <span class="md-ellipsis"> Coverage or chains? — which requirement view answers your question </span> </a> </li> <li class="md-nav__item"> <a href="../topics/credentials/" class="md-nav__link"> <span class="md-ellipsis"> Your password: changing it, resetting it — and why LQMS never sees it </span> </a> </li> <li class="md-nav__item"> <a href="../topics/emergency-cover/" class="md-nav__link"> <span class="md-ellipsis"> Who may cover for whom here — declaring emergency cover, and reading where the glass was broken </span> </a> </li> <li class="md-nav__item"> <a href="../topics/key-rules/" class="md-nav__link"> <span class="md-ellipsis"> Special elements: what a project declares, and when its names freeze </span> </a> </li> <li class="md-nav__item"> <a href="../topics/memberships/" class="md-nav__link"> <span class="md-ellipsis"> Belonging to an organization: invitations, acceptance, and what they change </span> </a> </li> <li class="md-nav__item"> <a href="../topics/provisioning-birth-path/" class="md-nav__link"> <span class="md-ellipsis"> How a new organization and project are born </span> </a> </li> <li class="md-nav__item"> <a href="../topics/review-policies/" class="md-nav__link"> <span class="md-ellipsis"> What a review policy controls, and what an empty grant means </span> </a> </li> <li class="md-nav__item"> <a href="../topics/setup-wizard-lanes/" class="md-nav__link"> <span class="md-ellipsis"> The setup wizard: the lanes, and what it writes </span> </a> </li> <li class="md-nav__item"> <a href="../topics/staffing-and-assignments/" class="md-nav__link"> <span class="md-ellipsis"> Staffing people into roles, and the accountable holder </span> </a> </li> <li class="md-nav__item"> <a href="../topics/technical-dossier/" class="md-nav__link"> <span class="md-ellipsis"> How do I assemble a technical dossier? </span> </a> </li> <li class="md-nav__item"> <a href="../trace-items/" class="md-nav__link"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> </li> <li class="md-nav__item"> <a href="../trace-links/" class="md-nav__link"> <span class="md-ellipsis"> Trace Links & the Suspect Cycle </span> </a> </li> <li class="md-nav__item"> <a href="../traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../training/" class="md-nav__link"> <span class="md-ellipsis"> Training & Acknowledgements </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-the-three-altitudes" class="md-nav__link"> <span class="md-ellipsis"> 1. The three altitudes </span> </a> <nav class="md-nav" aria-label="1. The three altitudes"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#where-administration-lives" class="md-nav__link"> <span class="md-ellipsis"> Where administration lives </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#2-admin--content--the-boundary-is-a-witness-not-a-fence" class="md-nav__link"> <span class="md-ellipsis"> 2. Admin ≠ content — the boundary is a witness, not a fence </span> </a> <nav class="md-nav" aria-label="2. Admin ≠ content — the boundary is a witness, not a fence"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#what-a-project-administrator-holds-exactly" class="md-nav__link"> <span class="md-ellipsis"> What a project administrator holds, exactly </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-the-life-of-a-project-scope" class="md-nav__link"> <span class="md-ellipsis"> 3. The life of a project scope </span> </a> <nav class="md-nav" aria-label="3. The life of a project scope"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#31-birth" class="md-nav__link"> <span class="md-ellipsis"> 3.1 Birth </span> </a> </li> <li class="md-nav__item"> <a href="#32-staffing-and-the-operating-model" class="md-nav__link"> <span class="md-ellipsis"> 3.2 Staffing and the operating model </span> </a> </li> <li class="md-nav__item"> <a href="#33-dissolution" class="md-nav__link"> <span class="md-ellipsis"> 3.3 Dissolution </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-the-life-of-a-person" class="md-nav__link"> <span class="md-ellipsis"> 4. The life of a person </span> </a> <nav class="md-nav" aria-label="4. The life of a person"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-external-kind--people-who-are-not-accounts" class="md-nav__link"> <span class="md-ellipsis"> The EXTERNAL kind — people who are not accounts </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#5-role-administration-and-the-closure-lesson" class="md-nav__link"> <span class="md-ellipsis"> 5. Role administration, and the closure lesson </span> </a> <nav class="md-nav" aria-label="5. Role administration, and the closure lesson"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-three-seeded-roles" class="md-nav__link"> <span class="md-ellipsis"> The three seeded roles </span> </a> </li> <li class="md-nav__item"> <a href="#the-closure-lesson" class="md-nav__link"> <span class="md-ellipsis"> The closure lesson </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#6-what-the-system-tells-you-the-setup-check-and-the-dead-end-philosophy" class="md-nav__link"> <span class="md-ellipsis"> 6. What the system tells you: the setup check and the dead-end philosophy </span> </a> <nav class="md-nav" aria-label="6. What the system tells you: the setup check and the dead-end philosophy"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-philosophy-in-four-rules" class="md-nav__link"> <span class="md-ellipsis"> The philosophy, in four rules </span> </a> </li> <li class="md-nav__item"> <a href="#what-it-flags" class="md-nav__link"> <span class="md-ellipsis"> What it flags </span> </a> </li> <li class="md-nav__item"> <a href="#the-chip-monitors-the-wizard-remediates" class="md-nav__link"> <span class="md-ellipsis"> The chip monitors; the wizard remediates </span> </a> </li> <li class="md-nav__item"> <a href="#the-principle-behind-all-of-it" class="md-nav__link"> <span class="md-ellipsis"> The principle behind all of it </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#7-when-an-administrator-must-not-act" class="md-nav__link"> <span class="md-ellipsis"> 7. When an administrator must NOT act </span> </a> </li> <li class="md-nav__item"> <a href="#8-break-glass-and-emergency-cover" class="md-nav__link"> <span class="md-ellipsis"> 8. Break-glass and emergency cover </span> </a> </li> <li class="md-nav__item"> <a href="#9-troubleshooting--the-refusals-an-administrator-meets" class="md-nav__link"> <span class="md-ellipsis"> 9. Troubleshooting — the refusals an administrator meets </span> </a> <nav class="md-nav" aria-label="9. Troubleshooting — the refusals an administrator meets"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#permission-refusals" class="md-nav__link"> <span class="md-ellipsis"> Permission refusals </span> </a> </li> <li class="md-nav__item"> <a href="#the-refusals-an-administrator-actually-meets" class="md-nav__link"> <span class="md-ellipsis"> The refusals an administrator actually meets </span> </a> </li> <li class="md-nav__item"> <a href="#symptoms-that-are-not-refusals" class="md-nav__link"> <span class="md-ellipsis"> Symptoms that are not refusals </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#10-the-operators-half--where-installation-and-maintenance-live" class="md-nav__link"> <span class="md-ellipsis"> 10. The operator's half — where installation and maintenance live </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://github.com/nburri/lqms/edit/main/docs/user-guide/administration.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <h1 id="administering-an-lqms-installation">Administering an LQMS Installation<a class="headerlink" href="#administering-an-lqms-installation" title="Permanent link">¶</a></h1> <p><em>Audience: whoever administers an installation and the scopes inside it without being a content person — the installation operator, an organization's administrator, and a project administrator.</em></p> <blockquote> <p><strong>This chapter describes LQMS v0.9.50.</strong> Everything in it is behaviour you can see in the running product today. The three things earlier editions marked as forthcoming have all landed: break-glass escalation and emergency cover (§8), and the permission-closure check that warns about the failure §5 describes (§6).</p> </blockquote> <p>Administering LQMS is not administering its documents. The people this chapter is written for staff roles, found and dissolve scopes, bring colleagues in and out, and keep an installation's governance legible — and most of them deliberately cannot read a line of the QMS content they administer. That separation is the product's central claim, and this chapter explains how to work with it rather than around it.</p> <blockquote> <p><strong>Judgment note.</strong> This chapter is the <em>product-admin</em> half. The <em>operator</em> half — installing, upgrading, backing up, restoring, TLS, secrets, the identity provider — is a separate trio of operations documents (§10) and is deliberately not repeated here: one description of a <code>docker compose</code> invocation is enough, and two would disagree within a release. Where the two halves meet — the bootstrap administrator, the installation's own organization, break-glass recovery — this chapter states what the <em>product</em> shows you and points at the operations document for the command.</p> </blockquote> <h2 id="1-the-three-altitudes">1. The three altitudes<a class="headerlink" href="#1-the-three-altitudes" title="Permanent link">¶</a></h2> <p>"Administrator" names three different jobs in LQMS, and almost every confusion in this area comes from treating them as one. They differ by <strong>where the person is staffed</strong>, and that single fact decides their reach.</p> <table> <thead> <tr> <th>Altitude</th> <th>Staffed at</th> <th>Administers</th> <th>Sees content?</th> </tr> </thead> <tbody> <tr> <td><strong>Installation administrator</strong></td> <td>the base scope, <code>GLOBAL</code></td> <td>the whole installation: organizations, cross-tenant provisioning, the catalog, users, backups, import/export</td> <td><strong>No</strong> — by construction</td> </tr> <tr> <td><strong>Organization-level administrator</strong></td> <td>an organization's own anchor scope</td> <td>every project of that one organization, present <em>and future</em>, including starting new ones</td> <td>Depends on the role's own permissions, inside that organization only</td> </tr> <tr> <td><strong>Project administrator</strong></td> <td>one project</td> <td>that one project: staffing, activation, policies, training</td> <td><strong>Yes</strong> — read-only, and only where the project activated the role</td> </tr> </tbody> </table> <p>Three rules make this table true rather than approximate.</p> <p><strong>Sovereignty flows downhill (ADR-0122).</strong> An assignment at an organization's anchor scope is effective in every current <em>and future</em> scope of that organization. That is the org-admin mechanism: there is no separate "org admin" switch, only a staffing at the anchor. Because a future project inherits it automatically, an organization that staffs its administrator once never has to remember to re-staff for project number seven.</p> <p><strong>A cascaded holder is shown where they act.</strong> A person staffed at the organization appears in each project's staffing view as a derived <em>"via organization"</em> row. This is not cosmetic: the four-eyes evaluator has always counted effective permissions, so an org-level approver held authority in a project while appearing nowhere in its roster — and a roster that hides an approver destroys the audit argument the roster exists to make. What an evaluator counts, a surface shows.</p> <p><strong>GLOBAL is different, in both directions (ADR-0128, ADR-0129).</strong> The base scope is a <em>cross-tenant</em> boundary, so a <code>GLOBAL</code> assignment is deliberately half-blind:</p> <ul> <li><strong>Administrative permissions cascade</strong> from <code>GLOBAL</code> into every scope — that is what running an installation means.</li> <li><strong>Content permissions do not.</strong> A content permission held via a <code>GLOBAL</code> assignment is effective in <code>GLOBAL</code> alone.</li> <li><strong>Role identity does not either.</strong> Workflow authority — approve, release, revoke, review — is gated by <em>which role you hold here</em>, not by a permission, so the same rule had to be drawn for it separately. A person holding an authoring role at <code>GLOBAL</code> holds it in the library and nowhere else.</li> </ul> <p>Read together: <strong>a <code>GLOBAL</code> grant means "run this installation and work in the shared library" — it never means "act inside somebody's project".</strong> The organization-anchor cascade is untouched by this and stays whole-class, because it stops at the organization boundary, which is exactly where the separation guarantee lives.</p> <h3 id="where-administration-lives">Where administration lives<a class="headerlink" href="#where-administration-lives" title="Permanent link">¶</a></h3> <p>The <strong>Admin</strong> area holds the installation-level surfaces. Each page is gated separately, so two administrators can see quite different menus:</p> <table> <thead> <tr> <th>Page</th> <th>What it is for</th> <th>Needs</th> </tr> </thead> <tbody> <tr> <td><strong>Users</strong></td> <td>the people surface: status, per-scope assignments, deactivate/reactivate, the accountable-holder star, organization invitations, and a separate <em>People from imported records</em> section (§4)</td> <td><code>MANAGE_USERS</code> in some scope</td> </tr> <tr> <td><strong>Roles</strong></td> <td>the installation's role catalog: create, rename, delete, set each role's permissions, and choose which scopes may use it</td> <td><code>MANAGE_CATALOG</code> at the base scope</td> </tr> <tr> <td><strong>Document types</strong></td> <td>the installation's document-type catalog and its per-type defaults</td> <td><code>MANAGE_CATALOG</code> at the base scope</td> </tr> <tr> <td><strong>Project setup</strong></td> <td>the setup wizard — birth and remediation (§3.1, §6)</td> <td><code>CONFIGURE_REVIEW_POLICY</code> in some scope</td> </tr> <tr> <td><strong>Found a new organization</strong></td> <td>founding a tenant, as its own workflow with its own entry point</td> <td><code>MANAGE_MANDATORS</code> at the base scope</td> </tr> <tr> <td><strong>Scopes</strong></td> <td>the project directory grouped by organization; renaming and the derive-source setting; dissolution</td> <td>reads widely; <strong>writes</strong> need <code>MANAGE_SCOPES</code> at the base scope</td> </tr> <tr> <td><strong>Activity</strong></td> <td>any scope's audit trail, newest first, with its own scope picker</td> <td>read per scope, server-side</td> </tr> <tr> <td><strong>System</strong></td> <td>backups (trigger, history, download), search reindex, sweep heartbeats, installation-level findings</td> <td><code>EXPORT_BACKUP</code> <strong>or</strong> <code>MANAGE_SYSTEM_SETTINGS</code> at the base scope, per section</td> </tr> </tbody> </table> <p>Two habits of the surface are worth knowing because they are house rules rather than quirks of one page:</p> <ul> <li><strong>An affordance the server would refuse is never shown as a disabled control that leaves you guessing.</strong> Either it is offered, or the reason it is absent is stated.</li> <li><strong>The Admin area tells you honestly when you hold nothing.</strong> Opening <code>/admin</code> forwards you to the first page whose gate you pass; if none does, it says <em>"You hold no installation-level administration"</em> rather than showing an empty shell.</li> </ul> <p>Per-project governance lives outside the Admin area, on the surfaces the project's own people use: <strong>Scope configuration</strong> (the gear — review policies, training, types, retention, project settings), <strong>Authority</strong> (who holds each function here, and what it may do), and <strong>My access</strong> (what <em>you</em> may do, per project, as the system enforces it right now). <em>My access</em> is the fastest way to answer "why can't this person do X?" when the person is you.</p> <h2 id="2-admin--content--the-boundary-is-a-witness-not-a-fence">2. Admin ≠ content — the boundary is a witness, not a fence<a class="headerlink" href="#2-admin--content--the-boundary-is-a-witness-not-a-fence" title="Permanent link">¶</a></h2> <p>This is the sentence to internalize, because it overturns the natural reading of the word "administrator", and because getting it wrong produces either a frustrated administrator or a compromised trail.</p> <p><strong>The boundary was never a capability limit.</strong> A project administrator holds the authority to staff people into roles — and <em>themselves</em> is one of the people. Anyone who can staff can staff their way into any role activated in their scope, and from there do anything that role can do. The master key is already in the administrator's own hand and always was, so no argument for widening the role can be made from "but he must be able to fix things". He must, and he can.</p> <p>What the boundary actually does is decide <strong>whether that rescue looks ordinary or exceptional in the record.</strong> If the administrator held standing content rights, the audit question <em>"who moved this, and under what authority?"</em> would get the answer <em>"the administrator, as usual"</em> — which is no answer. Separating the two makes the intervention a visible, bounded, named event instead of an unremarkable Tuesday. Since one person holds both keys anyway, separating them <strong>in time</strong> is the only separation available.</p> <blockquote> <p>The system's job is to hold the glass, not the key.</p> </blockquote> <p>Three consequences worth stating flatly:</p> <ul> <li><strong>The installation administrator's role carries no content permission at all.</strong> They cause trail entries they cannot themselves read. That is not a defect to be patched; it is admin ≠ content working, and it is why the installation operator can never quietly read a customer's QMS.</li> <li><strong>The Project Administrator role is the one recorded, narrow exception</strong>, and it is narrow on purpose: read access (<code>VIEW</code>, <code>VIEW_TRACEABILITY</code>) and nothing else from the content side. It is principled rather than a compromise, because at project level there is no cross-tenant boundary to cross: the catalog only <em>defines</em> the role, and the project must <strong>activate and staff</strong> it itself, inside its own trust domain.</li> <li><strong>Neither model touches four-eyes.</strong> Review and release discipline live in each document type's workflow role bindings and its review policy, never in an administrator's permission set. Widening or narrowing administration cannot loosen an approval chain — which is precisely why the choice between the models is about trail honesty and nothing else.</li> </ul> <h3 id="what-a-project-administrator-holds-exactly">What a project administrator holds, exactly<a class="headerlink" href="#what-a-project-administrator-holds-exactly" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>In — administer, staff, observe</th> <th>Out — deliberately</th> </tr> </thead> <tbody> <tr> <td><code>ASSIGN_ROLES</code> — staff people into activated roles</td> <td>every authoring/approval permission (<code>CREATE_DOCUMENT</code>, <code>EDIT_DRAFT</code>, <code>DERIVE</code>, <code>ORGANIZE_DOCUMENTS</code>)</td> </tr> <tr> <td><code>MANAGE_USERS</code> — administer people in this project</td> <td>the records-governance cluster (<code>DISPOSE_RECORDS</code>, <code>APPLY_LEGAL_HOLD</code>, <code>MANAGE_RETENTION</code>, <code>ERASE_PERSONAL_DATA</code>)</td> </tr> <tr> <td><code>ACTIVATE_CATALOG_ENTRIES</code> — activate roles and document types</td> <td>every installation-wide authority — this role administers a <em>project</em>, not the installation</td> </tr> <tr> <td><code>CONFIGURE_REVIEW_POLICY</code> — the governance box per type</td> <td></td> </tr> <tr> <td><code>MANAGE_TRAINING</code> — training rules and monitoring</td> <td></td> </tr> <tr> <td><code>CREATE_PROJECT</code> — but only where it is checked (see below)</td> <td></td> </tr> <tr> <td><code>VIEW</code>, <code>VIEW_TRACEABILITY</code> — read what you administer</td> <td></td> </tr> </tbody> </table> <p>The in/out lists are not maintained by hand. Every permission in the vocabulary carries a <strong>class</strong>, and the build fails when a newly added permission is not classified:</p> <ul> <li><strong>Content</strong> — reading and authoring the QMS: view, base-library read, the traceability and training and obligation reads, create, edit, derive, organize.</li> <li><strong>Project administration</strong> — staffing, user administration, catalog activation, review policy, training rules, project creation.</li> <li><strong>Global administration</strong> — the catalog itself, system settings, provisioning, portability (import/export), backups, dossier authority.</li> <li><strong>Records governance</strong> — dispose, legal hold, retention, personal-data erasure. A records-officer function, deliberately not bundled into administration: bundling would dilute both.</li> <li><strong>Retired</strong> — names that were declared and never enforced, removed rather than left lying around.</li> </ul> <p>The classification is not documentation about the boundary; it <strong>is</strong> the boundary. It decides what cascades out of <code>GLOBAL</code> (§1), so mis-classifying a new permission would change runtime reach — which is why the guard exists and why each classification carries a written argument.</p> <p><strong>The <code>CREATE_PROJECT</code> subtlety.</strong> Starting a project is checked at the <strong>target organization's anchor scope</strong> — never at <code>GLOBAL</code>, never inside a project. One permission in one list therefore means two different things depending on where the holder is staffed: a Project Administrator at an <em>organization's</em> scope may start that organization's projects; one staffed <em>in a project</em> holds the permission only where the check never looks, and can start nothing. If someone reports that they "have project-admin but cannot create a project", this is almost always the answer: they are staffed one altitude too low.</p> <h2 id="3-the-life-of-a-project-scope">3. The life of a project scope<a class="headerlink" href="#3-the-life-of-a-project-scope" title="Permanent link">¶</a></h2> <h3 id="31-birth">3.1 Birth<a class="headerlink" href="#31-birth" title="Permanent link">¶</a></h3> <p>A project is born through the <strong>setup wizard</strong>, and the birth is a one-party act: an organization or project administrator — including one who holds no content permission whatsoever — can carry a project from nothing to a complete, configured shape. The full walkthrough is <a href="../topics/provisioning-birth-path/">how a new organization and project are born</a>; what an administrator specifically needs to know:</p> <ul> <li><strong>Founding an organization</strong> and <strong>starting a project inside one</strong> are two different processes with two different authorities. Founding is installation-level (<code>MANAGE_MANDATORS</code>); starting a project is the organization's own business (<code>CREATE_PROJECT</code> at its anchor).</li> <li><strong>The code is identity; the name is a label.</strong> A project's code is minted into every document id in it, into cross-project references and into audit-pack manifests. There is no "change code" affordance anywhere in LQMS, and its absence is not an omission waiting to be filled — see <a href="../topics/admin-scopes/">renaming a project, and what can never change</a>.</li> <li><strong>The folder skeleton is a setting-up act, not a content act.</strong> While a scope holds <strong>zero</strong> documents, creating folders is gated like the rest of setup (<code>ACTIVATE_CATALOG_ENTRIES</code>), because an empty tree is scaffolding, not records. The moment the first document exists, the tree is live and <code>ORGANIZE_DOCUMENTS</code> governs it exactly as it governs any other reorganization. This is a structural line checked in the same transaction as the write — never a judgment the screen makes.</li> </ul> <p>That line exists because of a real failure: the wizard once told a content-blind operator to staff themselves into Quality Manager just to create folders. The remedy institutionalized the exact breach the boundary exists to prevent. <strong>The wizard no longer recommends self-staffing across the boundary anywhere in the birth path.</strong> Self-staffing remains available as what it always was — a deliberate act with content consequences — never a required workaround. - <strong>Staffing comes before policies</strong>, and that order is not a preference. See the birth-path topic §3.</p> <h3 id="32-staffing-and-the-operating-model">3.2 Staffing and the operating model<a class="headerlink" href="#32-staffing-and-the-operating-model" title="Permanent link">¶</a></h3> <p>Once the project exists, three verbs shape it, and they belong to different people at different altitudes:</p> <ol> <li><strong>Define</strong> — a role or document type exists in the installation's <strong>catalog</strong>. Catalog governance is installation-level by design; a project cannot mint a role for itself out of nothing.</li> <li><strong>Activate</strong> — the project decides which catalog entries it uses (<code>ACTIVATE_CATALOG_ENTRIES</code>). Nothing is staffable in a project until it is activated there.</li> <li><strong>Staff</strong> — a person is bound to an activated role in this project (<code>ASSIGN_ROLES</code>).</li> </ol> <p>Then the <strong>operating model</strong> on top: review policies per document type, key rules, training rules. See <a href="../topics/staffing-and-assignments/">staffing people into roles</a>, <a href="../topics/review-policies/">what a review policy controls</a>, and <a href="../topics/key-rules/">special elements and when their names freeze</a>.</p> <p>Two administrator-facing facts that live nowhere else:</p> <ul> <li><strong>Unstaffed roles are normal on day one.</strong> Invited people bind to their accounts on first login, so a project can be fully configured and still show unstaffed roles. The setup check tells you this; it does not block you (§6).</li> <li><strong>A virgin catalog needs the operator first.</strong> On a brand-new installation with no roles minted yet, someone with catalog authority has to create them before a project administrator has anything to activate. This is correct rather than a gap — the catalog is installation-level — but it is the one step of the birth path that a project-level administrator genuinely cannot perform alone.</li> </ul> <h3 id="33-dissolution">3.3 Dissolution<a class="headerlink" href="#33-dissolution" title="Permanent link">¶</a></h3> <p>A project born by mistake — a wrong code, a duplicated tenant, a test scope from week one — can be <strong>dissolved</strong>, and the rules around that act are the strongest statement this product makes.</p> <ul> <li><strong>The gate</strong> is <code>CREATE_PROJECT</code> effective at the project's <strong>organization anchor</strong>: create and un-create are one authority, and sovereignty stays inside the organization boundary.</li> <li><strong>The line</strong> is emptiness. A project is dissolvable while it holds no documents and no record-evidence rows — that is, while this instance has witnessed no act in it beyond setup. Drafts do not block dissolution (they are work, not records) and are destroyed with a counted confirmation. A <strong>released</strong> version does block, because an ordinary release <em>is</em> an approval act this instance witnessed.</li> <li><strong>The offer is the server's, not the screen's.</strong> The provisioning read answers whether a project may be dissolved; the frontend offers <em>Dissolve project…</em> exactly where the server said yes, and shows nothing at all to a caller without the gate. You will never meet a dissolve button that then refuses.</li> <li><strong>The trail outlives the scope.</strong> <code>SCOPE_DISSOLVED</code> is written at the organization anchor, beside the <code>SCOPE_CREATED</code> that opened its life, before the rows go and in the same transaction, with a counted payload (code, name, folders, activations, policies) — counts, never content. The organization's trail tells the whole life: born, shaped, dissolved.</li> <li><strong>Re-birth under a dissolved project's code is possible.</strong> No residue holds the code hostage.</li> </ul> <p><strong>What stays impossible, on every surface: deleting a scope this instance has witnessed real acts in.</strong> No identity anywhere — including the installation administrator — can destroy witnessed records. An any-status dissolve "with a clear record in the activity log" was explicitly considered and rejected: a log line preserves <em>that</em> something was destroyed, never <em>what</em>, and a global kill switch would be one identity able to destroy a tenant's scope. What can be destroyed is exactly what the system can prove nobody ever relied on. The remedy for a real scope that has finished its life is retirement and disposal with retention semantics, and every refusal names it.</p> <p>Dissolving an <strong>organization</strong> is the same principle one level up and is covered in the birth-path topic §6: it is offered only while the organization is still completely empty, and its own dissolution record makes an organization that has one permanent. A wrongly-named tenant can therefore be <strong>renamed</strong> but never dissolved once its trail has begun.</p> <h2 id="4-the-life-of-a-person">4. The life of a person<a class="headerlink" href="#4-the-life-of-a-person" title="Permanent link">¶</a></h2> <p>The mechanics — invitations, acceptance, assignments, the accountable holder, the personnel-change runbook — are covered in <a href="../topics/memberships/">belonging to an organization</a> and <a href="../topics/staffing-and-assignments/">staffing people into roles</a>. This section states the four things an administrator most often gets wrong.</p> <p><strong>Belonging and reach are different.</strong> A person exists <strong>once</strong> in the installation and belongs to organizations one membership at a time. Membership makes someone <em>staffable</em> and lists them in the roster; it shows them nothing. Only roles ever grant access. A brand-new member with no assignments is not a broken row — it is the staffable-but-unstaffed state.</p> <p><strong>There is no path around an invitation.</strong> Staffing a person into a project of an organization they do not belong to is refused, naming the person, the organization and the remedy — and the picker does not offer it in the first place, so you usually meet the rule as an absence rather than as an error. A role is given <em>inside</em> an organization somebody is in; it is never a way of putting them in one.</p> <p><strong>Accounts bind on first login, and LQMS never holds the password.</strong> An invited person is pre-created and binds to their real identity at the identity provider on their first login — but only if the identity provider says the <strong>email is verified</strong>. An unverified email never adopts a pending invitation, so a self-asserted address cannot inherit somebody else's pre-staffed roles. Reactivating someone who never bound returns them to <em>Invited</em>, so that binding still applies. Where credentials, resets and two-factor live is <a href="../topics/credentials/">your password</a>.</p> <p><strong>A person who signs in but was never invited belongs nowhere — and that is correct.</strong> If your identity provider lets someone authenticate who has no invitation here, LQMS creates them as an ordinary active person with <strong>no membership</strong>: no organization lists them, no scope reflects for them, and they see nothing at all. They appear only in the installation operator's user list, ready to be invited. A memberless person is not a leak; it is the honest representation of "authenticated, belongs nowhere yet". Authorization comes only from role assignments — never from having logged in.</p> <p><strong>Deactivation is installation-wide; ending a membership is not.</strong> Inviting, deactivating and reactivating a person are installation-wide acts, because a user is one global identity. Ending a <em>membership</em> is a single organization's authority: it unassigns every role that person held anywhere in that organization's scopes — each removal recorded at its own scope — and closes the membership. The person, their account and their history remain untouched. There is deliberately no code path from ending a membership to ending an account, which is the strongest form that guarantee can take: one organization can never switch off a person who also works elsewhere.</p> <p><strong>Deactivation does not unstaff anybody, and that is deliberate.</strong> A deactivated person keeps their memberships and role assignments; their access dies at the authentication edge, where every request they make is refused. Reactivation therefore restores exactly what they had, with no repair step — which is what makes the runbook in <a href="../topics/staffing-and-assignments/">staffing</a> §5 safe. Note the consequence for rosters: a deactivated person still <em>appears</em> as a holder, which is why the "no <strong>active</strong> holder" findings of §6 count activity rather than assignment.</p> <p>Two guards you will meet:</p> <ul> <li><strong>You cannot deactivate your own account.</strong> A deliberate footgun guard.</li> <li><strong>The last active system administrator cannot be deactivated, and cannot have their installation-wide administration role removed.</strong> An installation with no administrator cannot invite one, reactivate one or staff one — every repair path needs the authority that just vanished — so the system refuses rather than warns, and offers the <em>Deactivate</em> verb disabled with the reason on it. Appoint a second administrator first; then either may go. The guard holds even when two administrators try it on each other in the same moment.</li> </ul> <h3 id="the-external-kind--people-who-are-not-accounts">The EXTERNAL kind — people who are not accounts<a class="headerlink" href="#the-external-kind--people-who-are-not-accounts" title="Permanent link">¶</a></h3> <p>An installation that has imported a corpus from another QMS will find rows in the roster that are <strong>not accounts at all</strong>: <code>EXTERNAL</code> persons, minted so an imported history can say who brought it to its state. They are, by construction:</p> <ul> <li><strong>unbound</strong> — no identity at the identity provider, and they can never authenticate;</li> <li><strong>uninvitable and never mailed</strong> — they are outside the invitation flow entirely;</li> <li><strong>not staffable</strong> — they hold no roles and cannot be given any.</li> </ul> <p>They carry a <strong>provenance chip</strong> naming the source system they came from and when <em>this</em> instance minted the record, plus the codes of the projects whose document history references them. The chip answers "which source did this name come from"; the project list answers "where in my installation does this person actually turn up" — two different questions, and an administrator investigating an attributed release usually wants the second.</p> <p>Minting them is idempotent on their natural key (source plus email), so re-running an importer after a failure or a correction does not split one Hans Muster's corpus between two rows. An <code>EXTERNAL</code> person is deliberately excluded from the match key that binds live logins, so a real colleague who later joins never adopts a historical actor's record.</p> <h2 id="5-role-administration-and-the-closure-lesson">5. Role administration, and the closure lesson<a class="headerlink" href="#5-role-administration-and-the-closure-lesson" title="Permanent link">¶</a></h2> <h3 id="the-three-seeded-roles">The three seeded roles<a class="headerlink" href="#the-three-seeded-roles" title="Permanent link">¶</a></h3> <p>Every installation is born with three roles in its base catalog, ensured on <strong>every</strong> startup — so an installation that predates one of them gains it on upgrade, free:</p> <ul> <li><strong>System Administrator</strong> — the installation cut, assigned at <code>GLOBAL</code>. Carries every administrative permission and, deliberately, <strong>no content permission</strong>. Some of its grants are honest break-glass reach it cannot itself drive: it holds <code>MANAGE_DOSSIERS</code>, for instance, but no <code>VIEW</code>, so an installation grants dossier authority to the quality role that also holds <code>VIEW</code> in the scope.</li> <li><strong>Project Administrator</strong> — the per-project cut of §2, <strong>defined but never activated</strong>. The catalog defines it; a project activates and staffs it by its own deliberate act, which is exactly what licenses its read access.</li> <li><strong>Base Reader</strong> — carries exactly <code>BASE_READ</code> and nothing else, activated at <code>GLOBAL</code> (the only place that permission is effective). The invitation flow assigns it per person on acceptance, so base readership is visible and revocable per person instead of travelling as a passenger on somebody else's content role. Note that <strong>the bootstrap administrator holds no Base Reader</strong> — it never accepts an invitation — so grant it explicitly if the operator should read the library.</li> </ul> <p>Beyond those three, <strong>roles are entirely the installation's own vocabulary.</strong> There are no locked "system roles": the seeded three are a <em>floor, not a lock</em> — re-ensured on every boot, never stripped — so a role you tailored keeps your edits across upgrades. Roles are created, renamed, deleted, given their permissions and activated into scopes on <strong>Admin → Roles</strong>, which needs <code>MANAGE_CATALOG</code> at the base scope. The permission vocabulary itself is closed and extended only by a release: you choose which permissions a role holds, never what permissions exist.</p> <p>Deleting a role is refused while anything depends on it, and the refusal names the blockers — the scopes it is activated in, the people holding it — so the offer and the act can never disagree.</p> <p>A role's <strong>name is load-bearing at import</strong>: a bundle arriving with a role literally named "Project Administrator" or "Base Reader" adopts onto the seeded one rather than minting a second. Name beats function, by decision rather than by accident.</p> <h3 id="the-closure-lesson">The closure lesson<a class="headerlink" href="#the-closure-lesson" title="Permanent link">¶</a></h3> <p>This is the failure mode most worth knowing, because it produces a bug report with no bug in it.</p> <p>In a real imported project, nobody could move a document or set its language. The gate on the act (<code>ORGANIZE_DOCUMENTS</code>, the folder-move class) was correct. The staffed operating model was internally coherent: the Project Administrator held administration plus read, the quality role held create and edit, the reader roles held reads. But <strong>no staffed role held that one permission</strong>. A permission existed that belonged to nobody, and nothing in the system said so. Every actor was correct; the <em>set</em> had a hole in it.</p> <p>The lesson generalizes past that one permission:</p> <blockquote> <p>An operating model is not validated by checking each role. It is validated by checking the <strong>closure</strong> — that every permission the project's own acts will ask for is held by at least one role somebody actually holds.</p> </blockquote> <p><strong>Why the hole opens, and where.</strong> Permissions in LQMS imply nothing about one another: there is no "X therefore Y". They are also not implied by workflow function. Occupying the author, reviewer or releaser slot of a document type requires only the reading floor plus, for authoring, create and edit — <strong>nothing else comes with the job</strong>. Filing, language, retention, dossiers: each must be granted on purpose.</p> <p>That is exactly why <strong>an imported operating model is the highest-risk source of a coverage hole</strong>. The arrival import derives each created role's permissions from the <em>workflow slots</em> the source role occupied, and filing is not a workflow slot — so no imported model can ever produce a role holding <code>ORGANIZE_DOCUMENTS</code>. The setup wizard's lane presets do not have this hole: they give the Reviewer and Quality Manager roles filing rights deliberately, and give the Author role none, on the principle that <em>filing is a document-control act, not an authoring one</em>. A wizard-born project therefore arrives closed; an imported one arrives with whatever the source's slots implied.</p> <p><strong>Two structural answers now close it</strong>, and they are the same question one word apart:</p> <ul> <li><strong>At import</strong>, the role-mapping preview is the moment the operating model is still cheap to change, so that is where the closure belongs: before the model lands, the preview states which permissions would end up held by <strong>no</strong> role in the target scope.</li> <li><strong>In a running project</strong>, the setup check carries a <em>permission held by no staffed role</em> finding (§6), so a project that drifts into the hole says so before somebody hits the wall. It names the permission in words, quotes the catalog's own description of it, and names the two fixes — give the permission's holder a person, or give a person's role the permission.</li> </ul> <p><strong>Two ways to audit it by hand</strong>, which are still the right tools when you want to look rather than be told:</p> <ul> <li><strong>Admin → Roles</strong> searches by <strong>permission</strong>, not only by role name — type the permission and it names the roles carrying it. An empty answer is the hole.</li> <li><strong>Authority</strong> (per project) lays out role × holders × permissions × gaps, which is the same question asked from the staffing side.</li> </ul> <p>When the hole is real and somebody is stuck in it <em>now</em>, §8's break-glass is the sanctioned way through — a bounded, recorded step, not a substitute for the grant that fixes the model.</p> <p>The immediate remedy, when you meet it today, is ordinary and correct: <strong>grant the permission to the role that should have had it</strong> — in that incident, <code>ORGANIZE_DOCUMENTS</code> to the quality role — as a recorded catalog act. Do not solve it by staffing yourself into a content role and doing the work; §7 explains why.</p> <h2 id="6-what-the-system-tells-you-the-setup-check-and-the-dead-end-philosophy">6. What the system tells you: the setup check and the dead-end philosophy<a class="headerlink" href="#6-what-the-system-tells-you-the-setup-check-and-the-dead-end-philosophy" title="Permanent link">¶</a></h2> <p>An administrator's hardest question is <em>"is this project actually in order?"</em>, and LQMS answers it without being asked. The <strong>setup check</strong> on a project's configuration page is always on and always current: a chip reading <em>Setup complete</em> or <em>"N setup gaps"</em>, with the findings listed underneath and a fix link on each.</p> <p><img alt="The setup check with gaps" src="scene:scope-config-setup-gaps" /></p> <h3 id="the-philosophy-in-four-rules">The philosophy, in four rules<a class="headerlink" href="#the-philosophy-in-four-rules" title="Permanent link">¶</a></h3> <p><strong>Every finding mirrors a gate that already exists.</strong> The setup check invents no rules. Each finding is the <em>preview</em> of something that would otherwise fire as a surprise at somebody's first submit. That is why the wording of a finding and the wording of the refusal it predicts are the same sentence: re-reading the setup status right after a save can never contradict what the save just told you.</p> <p><strong>State, never a path.</strong> A finding describes what the scope <em>is</em>, never how it got there. Nothing records "was this founded by the wizard and then abandoned", and a resumed session, an API caller and the importer would each answer that differently — while the state answers identically for all three. This is also why an <strong>empty</strong> project is deliberately <strong>not</strong> flagged: a freshly provisioned scope with nothing activated is <em>unconfigured</em>, not a dead end, and shouting about missing roles on the wizard's first screen would only teach people to ignore the chip.</p> <p><strong>A withheld finding beats a false one.</strong> The check reads through the lens of what the caller may be told — content read, or the scope's governing permissions — and <code>complete</code> always means "complete as far as <em>you</em> may be told". A gap the caller may not see is simply not reported. The rule behind it: a withheld finding is a gap in what someone was told; a fabricated one is a lie about the scope.</p> <p><strong>The vocabulary is open.</strong> Findings carry a stable code plus a human sentence, and a surface meeting a code it does not know falls back to the sentence. New findings can therefore ship without every consumer being taught about them first.</p> <h3 id="what-it-flags">What it flags<a class="headerlink" href="#what-it-flags" title="Permanent link">¶</a></h3> <p>Two severities: <strong>warn</strong> — something an existing gate <em>will</em> block on — and <strong>hint</strong>, a soft "you probably want this". <code>Setup complete</code> means no findings at all, hints included.</p> <table> <thead> <tr> <th>Finding</th> <th>What it means for you</th> </tr> </thead> <tbody> <tr> <td><strong>No activated role</strong></td> <td>nobody can ever be staffed here and no workflow can run. Activate roles first — this is the day-one finding.</td> </tr> <tr> <td><strong>Type without review policy</strong></td> <td>new documents of the type start with empty workflow roles and cannot be submitted.</td> </tr> <tr> <td><strong>Unstaffed workflow role</strong></td> <td>a role taking part in a review workflow has no active holder, so submitting or releasing will be blocked. Normal on day one, while invited people have not yet logged in.</td> </tr> <tr> <td><strong>Unstaffed addressee role</strong></td> <td>documents address this role for training, so their acknowledgement obligation can never be met by anyone.</td> </tr> <tr> <td><strong>Unstaffed standing role</strong></td> <td>a role carrying a standing permission on a document type has no active holder, so nobody can exercise it.</td> </tr> <tr> <td><strong>Permission held by no staffed role</strong></td> <td>an authoring permission — filing documents, creating them, editing drafts — is held by no role that is both activated <em>and</em> staffed here, so the acts it gates are refused for <strong>everyone</strong> in the project. This is §5's closure hole, said out loud. The finding names the permission in plain words and both fixes: staff somebody into the role that holds it, or grant it to a role somebody holds.</td> </tr> <tr> <td><strong>Nobody may revoke / cancel / revise</strong></td> <td>the review policy grants a transition to no role. The <em>revoke</em> case on a <strong>prescribing</strong> type is the one that also <strong>refuses the save</strong> — a released procedure nobody can withdraw is not a configuration this system will store (ISO 13485 §4.2.4).</td> </tr> <tr> <td><strong>Trace type without key rule</strong></td> <td>the project has not declared the element kind, so it has no name or key prefix of its own and suggestions fall back to the built-in one.</td> </tr> <tr> <td><strong>Kind without defining type</strong></td> <td>an element kind is activated but no document type here may define it, so no item of it can be written anywhere.</td> </tr> <tr> <td><strong>Kind dependency unmet</strong></td> <td>an element kind is in use while a kind it depends on is not — the catalog supplies the explanation.</td> </tr> <tr> <td><strong>No folders</strong> <em>(hint)</em></td> <td>documents can only live at the root of this scope.</td> </tr> </tbody> </table> <p>Two siblings in the same grammar live on other surfaces:</p> <ul> <li><strong>An organization with no project and nobody in it</strong> shows on the provisioning directory — founded and then left standing, with the ways out named (found its first project, invite its first member, or dissolve it if it was a mistake).</li> <li><strong>No verified backup in 7 days</strong> shows on the System page. Read its sentence carefully: it reports what <em>this application</em> has recorded. Backups taken by the host's own <code>deploy/backup.sh</code> job run outside the application and do <strong>not</strong> appear here, so check the host's schedule before acting on this finding — see §10.</li> </ul> <h3 id="the-chip-monitors-the-wizard-remediates">The chip monitors; the wizard remediates<a class="headerlink" href="#the-chip-monitors-the-wizard-remediates" title="Permanent link">¶</a></h3> <p>These are two tools and confusing them wastes time both ways. The chip is the <strong>monitor</strong> — you never need the wizard to find out whether a project is in order, and re-running it as a routine health check is ceremony. Wizard re-entry is the <strong>remediation</strong> tool: it does the one thing the chip cannot, comparing the project against a whole <em>lane</em> and offering the entire difference as a single editable batch. Reach for it when a project was configured by hand or arrived through an import, when new document types were activated, or when you are adopting a lane's shape late. Details in <a href="../topics/setup-wizard-lanes/">the setup wizard</a> §6.</p> <h3 id="the-principle-behind-all-of-it">The principle behind all of it<a class="headerlink" href="#the-principle-behind-all-of-it" title="Permanent link">¶</a></h3> <blockquote> <p>Every process feature ships the derived answer to <em>"then what?"</em>.</p> </blockquote> <p>A gate that can block someone owes them a surface that says so in advance, in terms of <strong>state</strong> they can check, and a remedy they can act on. The setup check is that principle applied to project configuration; §8's refusals-become-doors is the same principle applied to the authorization layer.</p> <h2 id="7-when-an-administrator-must-not-act">7. When an administrator must NOT act<a class="headerlink" href="#7-when-an-administrator-must-not-act" title="Permanent link">¶</a></h2> <p>Everything in §2 was about what an administrator <em>may</em> do. This section is about the acts an administrator is capable of and should nevertheless refuse to perform, because performing them damages the record that the whole system exists to produce.</p> <p><strong>Do not author, approve or release content.</strong> Not because you cannot — you can staff yourself into any activated role in your scope — but because a document approved by the person who granted themselves the approval authority is the one combination access auditors like least, and the trail cannot tell it apart from ordinary work. The correct move is always the same shape:</p> <blockquote> <p><strong>Staff the right role, then let its holder act.</strong></p> </blockquote> <p><strong>Do not fix a stuck workflow by becoming the workflow.</strong> When someone reports that an action is missing, the answer is nearly always governance data rather than an act:</p> <table> <thead> <tr> <th>Symptom</th> <th>Where to look</th> <th>The administrator's act</th> </tr> </thead> <tbody> <tr> <td>"The Revise / Revoke / Cancel button is missing"</td> <td>the type's review policy — a row granted to nobody</td> <td>grant the transition to the role that person holds</td> </tr> <tr> <td>"Nobody can submit documents of this type"</td> <td>the same box: empty workflow groups, or no stored policy at all</td> <td>configure the policy</td> </tr> <tr> <td>"The permission exists but nothing happens"</td> <td>a grant to a role with <strong>no active holder</strong></td> <td>staff somebody, or re-point the grant</td> </tr> <tr> <td>"Nobody can move or re-file documents"</td> <td>permission closure — held by no staffed role (§5)</td> <td>grant it to the owning role</td> </tr> <tr> <td>"I have project-admin but cannot start a project"</td> <td>altitude — <code>CREATE_PROJECT</code> is checked at the organization anchor (§2)</td> <td>staff them at the organization, or start it for them</td> </tr> <tr> <td>"This person cannot be staffed here"</td> <td>membership — they do not belong to the organization</td> <td>invite them; acceptance makes them staffable</td> </tr> </tbody> </table> <p><strong>Do not rename to fix identity.</strong> If a project's <em>code</em> is genuinely wrong, the answer is a new project and a documented migration of its content — a deliberate, auditable act — not a rename that would silently re-identify a corpus already cited in released PDFs.</p> <p><strong>Do not test release workflows in a production scope.</strong> There is no admin key that makes a witnessed record disposable afterwards, and there deliberately never will be (§3.3). Until the declared sandbox scope kind arrives, use a scope you are willing to keep — or dissolve it <em>before</em> anything is released in it, while the emptiness line still holds.</p> <p><strong>Do not treat self-staffing as routine.</strong> It remains available and is sometimes right — an administrator genuinely is the "oh no, I have a problem" person. But <strong>use the timed door, not the permanent one</strong>: §8's break-glass staffs you for a declared window, records what you were trying to do, and takes the role back by itself, so the record shows an exceptional act as exceptional. Permanently staffing yourself into a content role looks exactly like ordinary staffing in the trail, and then the honesty of the record is entirely on you.</p> <h2 id="8-break-glass-and-emergency-cover">8. Break-glass and emergency cover<a class="headerlink" href="#8-break-glass-and-emergency-cover" title="Permanent link">¶</a></h2> <p>The auditor's question — <em>"how does your administrator intervene, and how would we know?"</em> — now has an answer you can point at on the screen rather than in a design document. The two mechanics below are the whole of it, and they have their own topics: <strong><a href="../topics/break-glass/">the door and the marker</a></strong> for the person meeting a refusal, <strong><a href="../topics/emergency-cover/">emergency cover</a></strong> for the person governing who may cover for whom. This section is the administrator's summary of both.</p> <p><strong>Break-glass escalation</strong> turns an administrator's rescue into a first-class act with a name, a moment and an end:</p> <ul> <li>A permission refusal stops being a wall and becomes <strong>the first step of the remedy</strong>. For a caller holding staffing authority in the scope, the refusal names the missing act, names which <em>activated</em> roles hold it, and offers the audited self-staffing act inline — <em>"You may take it on yourself — it will be recorded"</em>, with <strong>Staff yourself as QMB</strong> on the message. One click, one audited act, then you repeat the original act yourself: the door and the act stay separate, separately attributed things.</li> <li>The staffing carries a <strong>declared duration</strong> — 30 minutes, 60 minutes or 1 day, default 60 minutes — and a short optional note saying what you were trying to do, prefilled from the refused act.</li> <li><strong>Expiry is enforced by the authorization read itself, never by a cleanup job.</strong> If the janitor never runs, nothing is over-granted. A scheduled sweep only tidies the rows and writes the expiry event.</li> <li>The trail distinguishes <strong>three endings</strong>, because they are three different facts about a person: <em>Ended early</em> (handed back before the window closed, through <strong>End now</strong> — an actor), <em>Window closed</em> (expired as declared — no actor; the system honouring the window), and <em>Extended</em> (a <strong>fresh</strong> audited act with its own window, never a silent edit of the original).</li> <li>While any timed staffing is live, the application header carries a persistent chip — <em>"Acting as QMB — 42 min left"</em>, one per active role, shortening to <em>"QMB · 42 min"</em> on a narrower bar and folding into a single counted glyph on a phone. It turns <strong>amber with an hourglass</strong> in the last five minutes, and carries <strong>Extend…</strong> and <strong>End now</strong> in its own menu. It is a personal marker: others read the trail, not a badge on the person. It doubles as the pre-expiry warning, so nobody is ambushed mid-edit.</li> <li><strong>Ordinary staffing is untouched.</strong> Staffing other people, long-term, stays permanent.</li> </ul> <p><strong>Emergency cover</strong> generalizes the same mechanism beyond the administrator, and it is the reason the mechanism was pulled into 1.0:</p> <ul> <li>A per-project <strong>matrix of declared edges</strong> — <em>"a holder of role A may take over role B"</em> — declared by whoever governs roles there (the <em>Emergency cover</em> tab of the project's configuration page), as an audited governance act.</li> <li><strong>The declaration is the qualification statement.</strong> <em>"We judged A-holders competent to cover B"</em> is exactly what an auditor asks about substitution arrangements, and here it is a witnessed judgment with a name and a date rather than tribal knowledge on paper.</li> <li><strong>Own-name staffing, never impersonation.</strong> A substitute approving as B <em>is a different person approving</em>, which is precisely the fact four-eyes exists to establish. The trail says <em>"she held QMB, from then until then"</em> — never <em>"she acted for him"</em>. Impersonation is permanently rejected.</li> <li><strong>Edges may only target content-class roles</strong>, refused at declaration time by the server, in the server's own words. An edge into an administrative role would hand the master key through a side door. An absent <em>administrator</em> is covered through the organization level (§1), never through the matrix.</li> <li><strong>Emergency is not planned absence.</strong> The matrix carries short windows and answers "the role-holder is unreachable and the act is stuck <em>now</em>". A vacation is ordinary, deliberate staffing of a deputy by the administrator. Folding planned absence into the self-service path would normalize the exceptional act, which is the failure this whole design exists to prevent: the matrix is glass to break, not a schedule.</li> <li><strong>Not built, by decision:</strong> transitive edges (A-covers-B plus B-covers-C grants A nothing toward C — every edge is its own declared judgment) and cross-scope edges (cover across scopes is staffing, not substitution).</li> </ul> <p><strong>Read it as a rollout diagnostic, not only as an audit trail.</strong> The same tab lists every timed staffing, extension, early end, expiry and cover declaration the project has seen. In an installation's first months that list is the most useful map you have of where the <em>declared</em> operating model missed reality: each entry marks a place where somebody had to work around the model to get work done. Fix what the list points at — a permission nobody holds, a role nobody is staffed into — and the list stops growing, which is the outcome you want. §7's discipline still applies on top: staff deliberately, and let the trail say what happened.</p> <h2 id="9-troubleshooting--the-refusals-an-administrator-meets">9. Troubleshooting — the refusals an administrator meets<a class="headerlink" href="#9-troubleshooting--the-refusals-an-administrator-meets" title="Permanent link">¶</a></h2> <p>Since v0.9.40, refusals speak human. The rule is binding rather than stylistic: <strong>a refusal names what is missing and where, in human terms — never a permission constant, never a scope UUID.</strong> The server publishes the <em>facts</em> (which permission, which scope) and the screen composes the sentence, because a client cannot humanize a sentence but it can humanize facts. The trigger was an operator meeting <code>ORGANIZE_DOCUMENTS required in scope 06ab83d3-…</code> and having to look up both halves.</p> <h3 id="permission-refusals">Permission refusals<a class="headerlink" href="#permission-refusals" title="Permanent link">¶</a></h3> <p>The sentence you get says as much as the server could honestly establish, and no more. There are three endings, in rising order of how much help they can offer:</p> <blockquote> <p><strong>In <em>QMS Operations</em> you do not have the permission to staff people into roles. Ask someone who holds it there.</strong></p> <p><strong>… It is held there by <em>Quality Manager</em> — ask one of them.</strong></p> <p><strong>… You may take it on yourself — it will be recorded.</strong> — with the act on the message: <strong>Staff yourself as Quality Manager</strong>.</p> </blockquote> <p>The second and third forms are §8's work: the server names which <em>activated</em> roles hold the missing permission, and marks the ones you could legitimately take on yourself. Nothing is inferred — a refusal that names no roles means the server named none, not that none exist.</p> <p>The act itself is named in plain words in all three — <em>provision and deactivate users</em>, <em>maintain the global catalogs and the role permissions</em>, <em>manage organizations</em>, <em>create projects</em>, <em>activate roles and document types here</em>, <em>organize documents into folders</em>, <em>read the base library</em>. When an act has no phrase yet, the sentence degrades to <em>"You do not have the permission this needs"</em> — never to the raw constant. When the scope cannot be resolved for you, the "where" is dropped rather than printed as a UUID. And when no single permission is missing — the configuration read, which several permissions can satisfy — you get the scope-only form: <em>"You do not have the permission this needs in </em><em>X</em><em>."</em></p> <h3 id="the-refusals-an-administrator-actually-meets">The refusals an administrator actually meets<a class="headerlink" href="#the-refusals-an-administrator-actually-meets" title="Permanent link">¶</a></h3> <p>Each of these is a full sentence from the server, rendered to you verbatim, and each names its own remedy.</p> <p><strong>Staffing and people</strong></p> <table> <thead> <tr> <th>You tried to</th> <th>You get, in substance</th> </tr> </thead> <tbody> <tr> <td>Deactivate the last system administrator</td> <td><em>"…is the last active system administrator — deactivating them would leave this installation with nobody who can administer users, and nobody able to undo it. Appoint a second system administrator first…"</em> The screen pre-empts this: the verb is offered <strong>disabled with the reason on it</strong>.</td> </tr> <tr> <td>Staff someone into a project of an organization they do not belong to</td> <td><em>"…does not belong to 'X', and 'CODE' is one of its scopes — a role can only be given inside an organization the person is a member of. Invite them to the organization first; once they accept, this role can be assigned (an invitation can also carry it, so it applies the moment they accept)."</em></td> </tr> <tr> <td>Assign a role that is not activated here</td> <td><em>"role 'Regulatory Affairs' is not activated in scope 'CARDIO'"</em> — both named, so you know exactly which activation to add.</td> </tr> <tr> <td>Staff, deactivate or invite an imported person</td> <td><em>"…is an external person imported from 'MERIDIAN-QMS' — a record of history, not an account here. External persons cannot be staffed: they have no login and never receive mail. To give this person access, invite their email address; that creates their own account beside the imported record."</em> (§4)</td> </tr> <tr> <td>Deactivate your own account</td> <td><em>"you cannot deactivate your own account"</em></td> </tr> <tr> <td>Invite yourself into an organization</td> <td><em>"An invitation is an offer one person makes to another, and accepting it is the other person's answer — ask another administrator of 'X' to invite you."</em></td> </tr> <tr> <td>Invite someone who already holds a role there</td> <td><em>"…already belongs to 'X' — they hold a role in one of its scopes, which is what belonging to an organization means. There is nothing left to invite them to."</em></td> </tr> <tr> <td>Invite a deactivated person</td> <td><em>"…is deactivated and cannot accept an invitation — reactivate the account first."</em></td> </tr> <tr> <td>Invite into an organization with no anchor scope</td> <td><em>"…has no mandator-level scope, and membership is anchored there… Create a MANDATOR scope for 'X' first (Admin › Scopes), then invite people into it."</em></td> </tr> <tr> <td>Answer someone else's invitation</td> <td><em>"An invitation is answered by the person it was sent to."</em></td> </tr> </tbody> </table> <p>A person whose account has been deactivated meets a single sentence on <strong>every</strong> request — <em>"User account is deactivated"</em> — because access dies at the authentication edge rather than by unstaffing. Their memberships and assignments are deliberately left intact, so reactivating restores exactly what they had.</p> <p><strong>Scopes and dissolution</strong></p> <table> <thead> <tr> <th>You tried to</th> <th>You get, in substance</th> </tr> </thead> <tbody> <tr> <td>Dissolve an organization that has recorded something</td> <td><em>"'X' is not empty — it still has 2 projects ('Alpha', 'Beta'), 3 membership records, 14 audit-trail entries. Only an organization that has recorded nothing at all can be dissolved, because dissolving it must destroy nothing; anything that ever held content or a trail stays permanent."</em> — the holdings are <strong>counted and named</strong>, so you know precisely what to look at.</td> </tr> <tr> <td>Dissolve a project holding releases</td> <td><em>"…holds 7 released versions. Drafts in a project may still be thrown away with it, but a release is an act this instance witnessed — somebody here approved that document and put it into force, and everybody after them was entitled to rely on it. Retiring a project that holds records is disposal — with retention semantics and an archive of record — which this act is not, and never becomes."</em></td> </tr> <tr> <td>Dissolve a project under legal hold</td> <td><em>"…is under a legal hold, so nothing in it may be destroyed — including the project itself. Release the hold first if it no longer applies."</em></td> </tr> <tr> <td>Dissolve an import-born project</td> <td><em>"…arrived through an import, and the import's own record governs its lifecycle (Admin › Import). Dissolving it here would destroy that record as a side effect, which an import record must never be."</em></td> </tr> <tr> <td>Dissolve the base scope or an organization's anchor</td> <td><em>"…is not a project. The installation's base scope belongs to the bootstrap, and an organization's own scope is dissolved with the organization…"</em></td> </tr> <tr> <td>Dissolve without the authority</td> <td>the sentence that teaches the whole altitude rule: dissolving needs <code>CREATE_PROJECT</code> <strong>in the organization the project belongs to</strong> — <em>"hold it at an organization's own scope and you may end that organization's unused projects; hold it inside a single project and it reaches nothing, because this act is never checked in a project. MANAGE_SCOPES, which shapes the installation, is a different authority and does not end a project."</em></td> </tr> <tr> <td>Dissolve while somebody records something</td> <td><em>"…could not be dissolved: something was recorded in it while the dissolution was running, so it is no longer a project this installation has never worked in. </em><em>Nothing was destroyed.</em><em> Read the project again — if it now holds records, they are permanent."</em></td> </tr> <tr> <td>Rename the base scope</td> <td><em>"The global base scope's name belongs to the installation bootstrap — it is the installation's own scope, not a project that can be relabelled."</em></td> </tr> <tr> <td>Give an organization a second anchor scope</td> <td><em>"…already has a mandator-level scope ('CODE') — a tenant has exactly one, because it is the single anchor its memberships are governed and audited at. Create a PROJECT scope instead, or rename the existing one (Admin › Scopes)."</em></td> </tr> <tr> <td>Choose an organization to work in, without authority</td> <td><em>"MANAGE_SCOPES at the installation level, or CREATE_PROJECT at an organization's own scope, is required to choose an organization to work in."</em></td> </tr> </tbody> </table> <p><strong>One refusal that means the installation is not up yet:</strong> <em>"no GLOBAL scope exists; bootstrap the installation first"</em>. That is an operator-level condition, not an administration one — the bootstrap did not run. See §10.</p> <h3 id="symptoms-that-are-not-refusals">Symptoms that are <em>not</em> refusals<a class="headerlink" href="#symptoms-that-are-not-refusals" title="Permanent link">¶</a></h3> <p>The hardest cases produce no error at all, because nothing is broken — the governance data simply never said yes. §7's table is the index for these; the two most common:</p> <ul> <li><strong>An action is simply absent.</strong> A half-configured review policy locks people out of every transition nobody was granted, silently. When somebody reports <em>"the button is missing"</em>, open the review policy box for that document's type and look for the <strong>⚠ nobody</strong> markers.</li> <li><strong>Everyone is correct and nothing works.</strong> That is the closure hole of §5: a permission held by no staffed role. The setup check does complain about it now — <em>permission held by no staffed role</em>, on the project's configuration page (§6) — so start there rather than reading the operating model role by role. It is a <em>set</em> property, and that is the surface that evaluates it as one.</li> </ul> <h2 id="10-the-operators-half--where-installation-and-maintenance-live">10. The operator's half — where installation and maintenance live<a class="headerlink" href="#10-the-operators-half--where-installation-and-maintenance-live" title="Permanent link">¶</a></h2> <p>This chapter stops at the edge of the product. Everything below it — the host, the containers, the identity provider, the bytes — lives in three operations documents, and they are the authority:</p> <ul> <li><strong><a href="../../operations/server-deployment/">server-deployment.md</a></strong> — the reference installation on a single Linux host with public HTTPS: topology and sizing, DNS and firewall, the published image and its registry credential, secrets, bring-up, Keycloak administration, corpus import and export, <strong>backups and the restore rehearsal</strong>, secret rotation, the upgrade ritual, the first-deploy checklist, and a troubleshooting section for the infrastructure failures (issuer mismatch, login loops, certificates, <code>exec format error</code>).</li> <li><strong><a href="../../operations/deployment/">deployment.md</a></strong> — the configuration reference: every property, the database roles and the <code>BYPASSRLS</code> requirement, OIDC integration, the <strong>bootstrap admin flow</strong>, email enablement, sweep tuning, the upgrade path, the backup and retention window, and how to verify a deployment.</li> <li><strong><a href="../../operations/genesis-installation/">genesis-installation.md</a></strong> — standing up an installation whose QMS <em>arrives</em> as a portability bundle: the phase order from preflight through landing the library, the retirement wave, per-project landing, staffing and verification.</li> </ul> <p>Three meeting points between the two halves are worth naming here, because they surprise people:</p> <p><strong>The bootstrap administrator is configuration, not a user you create.</strong> Two properties — <code>lqms.bootstrap.admin.subject</code> and <code>.email</code> — must both be set for the bootstrap to run; without them it is skipped and says so in the log (<code>.display-name</code> is optional). The subject must be the administrator's stable OIDC <code>sub</code> at your identity provider: identities are matched on <strong>subject alone</strong>, so a wrong subject silently grants the wrong account.</p> <p>The bootstrap runs on <strong>every</strong> boot, idempotently, and it is both initial setup and the operator-level recovery path if an installation ever loses its administrator despite the last-admin guard (§4). This is a different thing from the in-app break-glass of §8: it is performed on the host by whoever can restart the service, and it re-grants <em>installation administration</em> rather than temporary content reach.</p> <p>What it ensures each time: the base scope, the internal tenant with its <code>ORG</code> anchor and <code>QMS-OPS</code> project, the three seeded roles (§5), and the configured identity assigned System Administrator at <code>GLOBAL</code>. The seeded permission sets are a <strong>floor, not a lock</strong> — nothing is ever removed, so an installation that tailored a role through the catalog keeps its edits across upgrades.</p> <p><strong>The installation founds its own organization, once.</strong> Bootstrap creates the base scope <code>GLOBAL</code>, the installation's own internal organization with its anchor and operations scopes, and the seeded roles. The tenant's name comes from <code>LQMS_ORG_NAME</code> and is applied <strong>only at creation</strong>: the bootstrap never renames, because the name is a renameable label and a rename is a governed, audited act on the provisioning surface. Name the tenant truthfully before the first boot — a wrongly-named tenant can be renamed but, once its trail has begun, never dissolved.</p> <p><strong>Backups are the operator's, and they are the archive of record.</strong> Retention arguments that reach past what the live system holds — a dissolved scope, a migrated corpus, everything a genesis rebuild deliberately loses — rest on a named backup, not on the database. The schedule, the off-server copy, and the restore rehearsal that turns a backup into evidence are in <code>server-deployment.md</code> §9.</p> <hr /> <p><em>Governing decisions: ADR-0012 / REQ-ADM-004 (admin ≠ content — the boundary, absolute at GLOBAL), ADR-0010 (the base hierarchy the bootstrap creates), ADR-0121 (the Project Administrator: the per-project cut, its read access, and the classification guard), ADR-0122 (organization-level administration: the cascade kept and made visible, <code>CREATE_PROJECT</code> split out and checked at the target anchor, the birth path opened to org administrators), ADR-0124 (the birth path completes without borrowing content clothes — the empty-scope bright line for folders), ADR-0126 (project dissolution: the creation-mirror gate, the emptiness line, the trail that outlives the scope, and what stays impossible), ADR-0128 (the GLOBAL cascade carries administration, never content), ADR-0129 (role identity from a GLOBAL assignment acts in GLOBAL alone), ADR-0130 (break-glass — refusals become doors, timed self-staffing enforced by the authorization read, the header marker, and the permission-closure check of §5/§6), ADR-0131 (emergency cover as declared adoption edges), ADR-0117 (role documentation; acting-as/impersonation rejected — the rejection §8 stands on), ADR-0108 (tenant self-administration: invitations, membership, credentials), ADR-0111 §1 (EXTERNAL persons — imported historical actors), ADR-0127 §3 (the Base Reader role), ADR-0097 (the governed provisioning surface), ADR-0107 (assignment-reach audit anchoring — why an administrator can cause trail entries they cannot read), ADR-0064 (workflow role bindings — why administration cannot loosen four-eyes), ADR-0106 (derived facts: <code>mayBeDissolved</code> and the "via organization" rows), ADR-0007 (never show an affordance the server refuses), ADR-0099 (this manual ships with the version it documents). Regulatory frame: ISO 13485 §5.5.1 (responsibility and authority), §4.2.4 (control of documents), §4.2.5 (control of records); IEC 62304 §5.1 (planning and personnel).</em></p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../tutorial/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Tutorial — from zero to a released document"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> Tutorial — from zero to a released document </div> </div> </a> <a href="../diagrams/" class="md-footer__link md-footer__link--next" aria-label="Next: Diagrams"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Diagrams </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Built from <code>v0.9.56-4-g06c7f811</code> (commit <code>06c7f811</code>, 2026-09-09) — the same Markdown the repository ships. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.top", "navigation.footer", "navigation.indexes", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.action.edit"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script> </body> </html>