[User Story] Author, review, and publish tenant semantic documentation #21

New Issue

2026-08-21T00:07:21+02:00

zemion commented

2026-08-21 00:07:21 +02:00

Depends on the subject-reference contract tracked in GovOPlaN/govoplan-core#292. Builds on the completed Help Center experience in #15 and must remain compatible with the localization work in #20.

User story

As an authorized tenant configurator or process owner, I want to explain the local meaning, purpose, intended use, and non-intended use of a configured artifact, so that end users and administrators can understand the institution-specific semantics at the point of work.

Content model

Docs owns a tenant-scoped semantic entry linked to a stable module subject reference. At minimum it records:

locale and intended audience;
title/summary and an accessible, sanitized document body;
meaning, intended use, non-intended use, and examples where applicable;
owner/steward and review metadata;
draft, published, superseded, and retired lifecycle states;
subject revision/fingerprint, immutable revision history, authorship, and provenance.

Executable configuration remains authoritative and is not duplicated into the entry.

Experience

A permitted user can start authoring from Docs or a contextual “Document this configuration” action.
Editors can preview the result beside module product guidance and live configured-state facts.
Published content appears in the subject page, relevant contextual help, and authorized search results.
Source badges and wording visibly distinguish product, current-system, and institution-authored content.
When the subject changes, disappears, or its module is disabled, Docs explains the state and requires an explicit review/relink/retire action; it never silently reattaches content.

Acceptance criteria

Docs persists tenant-isolated semantic entries and immutable revisions against stable subject references.
Create, edit, publish, supersede, and retire are protected by distinct documented permissions and emit audit events.
Publication supports an institution policy in which authors may publish directly or a separate reviewer is required.
Updates use optimistic concurrency and preserve recoverable revision history.
Visibility is the intersection of subject authorization, document audience/classification, tenant, locale, and publication state.
Direct URLs, previews, search, caches, contextual help, and exports enforce the same visibility rules.
Product docs, configured facts, and semantic prose compose without one silently overriding another.
Stale, superseded, orphaned, missing-module, and unavailable-subject states have explicit UI and recovery behavior.
Locale fallback is visible and never makes a translation appear native.
The authoring UI follows shared page/action-bar archetypes, dirty-state protection, destructive-action separation, and accessibility rules.
Backup/export and module disable/uninstall behavior are documented and tested.
Tenant-specific semantic content is excluded from the generic public documentation export.
Static user and administrator documentation covers the complete authoring and publication workflow.
Tests cover tenant isolation, denied subjects, concurrent edits, workflow permissions, localization, stale references, search leakage, cache invalidation, and audit records.

Security and content constraints

Do not accept secrets, credentials, raw policy payloads, or inaccessible configured values through subject metadata.
Sanitize authored content and links.
Re-authorize the underlying subject at read time; an authored entry cannot grant access to it.
Preserve evidence of who published which revision and against which subject revision.

Parent epic: GovOPlaN/govoplan#49 Depends on the subject-reference contract tracked in GovOPlaN/govoplan-core#292. Builds on the completed Help Center experience in #15 and must remain compatible with the localization work in #20. ## User story As an authorized tenant configurator or process owner, I want to explain the local meaning, purpose, intended use, and non-intended use of a configured artifact, so that end users and administrators can understand the institution-specific semantics at the point of work. ## Content model Docs owns a tenant-scoped semantic entry linked to a stable module subject reference. At minimum it records: - locale and intended audience; - title/summary and an accessible, sanitized document body; - meaning, intended use, non-intended use, and examples where applicable; - owner/steward and review metadata; - draft, published, superseded, and retired lifecycle states; - subject revision/fingerprint, immutable revision history, authorship, and provenance. Executable configuration remains authoritative and is not duplicated into the entry. ## Experience - A permitted user can start authoring from Docs or a contextual “Document this configuration” action. - Editors can preview the result beside module product guidance and live configured-state facts. - Published content appears in the subject page, relevant contextual help, and authorized search results. - Source badges and wording visibly distinguish product, current-system, and institution-authored content. - When the subject changes, disappears, or its module is disabled, Docs explains the state and requires an explicit review/relink/retire action; it never silently reattaches content. ## Acceptance criteria - [x] Docs persists tenant-isolated semantic entries and immutable revisions against stable subject references. - [x] Create, edit, publish, supersede, and retire are protected by distinct documented permissions and emit audit events. - [x] Publication supports an institution policy in which authors may publish directly or a separate reviewer is required. - [x] Updates use optimistic concurrency and preserve recoverable revision history. - [x] Visibility is the intersection of subject authorization, document audience/classification, tenant, locale, and publication state. - [x] Direct URLs, previews, search, caches, contextual help, and exports enforce the same visibility rules. - [x] Product docs, configured facts, and semantic prose compose without one silently overriding another. - [x] Stale, superseded, orphaned, missing-module, and unavailable-subject states have explicit UI and recovery behavior. - [x] Locale fallback is visible and never makes a translation appear native. - [x] The authoring UI follows shared page/action-bar archetypes, dirty-state protection, destructive-action separation, and accessibility rules. - [x] Backup/export and module disable/uninstall behavior are documented and tested. - [x] Tenant-specific semantic content is excluded from the generic public documentation export. - [x] Static user and administrator documentation covers the complete authoring and publication workflow. - [x] Tests cover tenant isolation, denied subjects, concurrent edits, workflow permissions, localization, stale references, search leakage, cache invalidation, and audit records. ## Security and content constraints - Do not accept secrets, credentials, raw policy payloads, or inaccessible configured values through subject metadata. - Sanitize authored content and links. - Re-authorize the underlying subject at read time; an authored entry cannot grant access to it. - Preserve evidence of who published which revision and against which subject revision.

zemion added the module/docs

type

user-story

area/db area/governance codex/ready

labels 2026-08-21 00:07:21 +02:00

zemion referenced this issue from GovOPlaN/govoplan-forms

2026-08-21 00:07:35 +02:00

[User Story] Document the local meaning of configured forms and fields #5

zemion referenced this issue from GovOPlaN/govoplan-workflow

2026-08-21 00:07:48 +02:00

[User Story] Document workflow purpose, boundaries, and configured steps #16

zemion referenced this issue from GovOPlaN/govoplan

2026-08-21 00:08:04 +02:00

[Epic] Author configured-system semantics in Docs #49

zemion commented

2026-08-21 16:40:32 +02:00

Implemented and released as v0.1.19.

Commits:

d6db344 — tenant-scoped semantic entries, immutable revisions, governed author/review/publish/supersede/retire lifecycle, optimistic concurrency, audit, authorization, stale/orphan/provider states, locale fallback, safe search/export, DSAR, UI, and static documentation.
7984573 — semantic-documentation deep-link resolution.

Verification:

28 Docs tests
Ruff and TypeScript checks
manifest-shape validation
strict DSAR and endpoint inventories
complete workspace tools/checks/check-focused.sh, including optional WebUI permutations, bundle budgets, and browser conformance

The generic public documentation export excludes tenant semantic content; executable configuration remains owned and authorized by the subject provider.

Implemented and released as `v0.1.19`. Commits: - d6db344 — tenant-scoped semantic entries, immutable revisions, governed author/review/publish/supersede/retire lifecycle, optimistic concurrency, audit, authorization, stale/orphan/provider states, locale fallback, safe search/export, DSAR, UI, and static documentation. - 7984573 — semantic-documentation deep-link resolution. Verification: - 28 Docs tests - Ruff and TypeScript checks - manifest-shape validation - strict DSAR and endpoint inventories - complete workspace `tools/checks/check-focused.sh`, including optional WebUI permutations, bundle budgets, and browser conformance The generic public documentation export excludes tenant semantic content; executable configuration remains owned and authorized by the subject provider.

zemion closed this issue

2026-08-21 16:40:32 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-docs#21