Seed docs workflow and concept docs

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: "Bug"
+about: "Report a reproducible defect, regression, or incorrect behavior"
+title: "[Bug] "
+labels:
+  - type/bug
+  - status/triage
+  - module/docs
+---
+
+## Scope
+
+- Repository:
+- Area/module:
+- Affected version or commit:
+
+## Behavior
+
+Expected:
+
+Actual:
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Evidence
+
+Logs, screenshots, traces, or failing test output:
+
+## Verification Target
+
+Command or workflow that should pass when fixed:

.gitea/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.gitea/ISSUE_TEMPLATE/docs_workflow.md

@@ -0,0 +1,27 @@
+---
+name: "Docs / workflow"
+about: "Request documentation, process, or developer workflow changes"
+title: "[Docs] "
+labels:
+  - type/docs
+  - status/triage
+  - module/docs
+  - area/docs
+---
+
+## Scope
+
+- Repository:
+- Document or workflow:
+
+## Current State
+
+What is missing, unclear, duplicated, or stale?
+
+## Desired State
+
+What should the docs or workflow make clear?
+
+## Verification Target
+
+How should this be checked?

.gitea/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: "Feature"
+about: "Propose new user-visible behavior or platform capability"
+title: "[Feature] "
+labels:
+  - type/feature
+  - status/triage
+  - module/docs
+---
+
+## Problem
+
+What user, operator, or developer problem should this solve?
+
+## Proposed Capability
+
+What should exist when this is done?
+
+## Ownership
+
+- Owning repository:
+- Related module repositories:
+- Extension point or integration boundary:
+
+## Acceptance Criteria
+
+- [ ]
+- [ ]
+
+## Verification Target
+
+Command, scenario, or UI flow that should prove completion:

.gitea/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,28 @@
+---
+name: "Task"
+about: "Track implementation, maintenance, or migration work"
+title: "[Task] "
+labels:
+  - type/task
+  - status/triage
+  - module/docs
+---
+
+## Objective
+
+What needs to be completed?
+
+## Scope
+
+- Owning repository:
+- In-scope:
+- Out-of-scope:
+
+## Checklist
+
+- [ ]
+- [ ]
+
+## Verification Target
+
+Command or manual check:

.gitea/ISSUE_TEMPLATE/tech_debt.md

@@ -0,0 +1,25 @@
+---
+name: "Tech debt"
+about: "Track cleanup, refactoring, risk reduction, or deferred engineering work"
+title: "[Debt] "
+labels:
+  - type/debt
+  - status/triage
+  - module/docs
+---
+
+## Current Cost
+
+What does this make harder, riskier, slower, or more fragile?
+
+## Desired Shape
+
+What should the code, tests, or architecture look like afterwards?
+
+## Constraints
+
+What behavior, compatibility, or module boundary must be preserved?
+
+## Verification Target
+
+Focused checks that should pass:

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Issue
+
+Closes #
+
+## Summary
+
+-
+
+## Verification
+
+-
+
+## Notes
+
+Follow-up issues:

AGENTS.md

@@ -0,0 +1,31 @@
+# GovOPlaN Docs Codex Guide
+
+## Scope
+
+This repository owns the `docs` module: configured-system documentation, documentation source contracts, evidence-aware help, documentation route contributions, module documentation indexing, docs-owned migrations if needed, and future `@govoplan/docs-webui`.
+
+The module should describe the system that is actually configured first. It may show evidence about additional capabilities, installed-but-disabled features, or available extensions, but it should not force users through full-system documentation when their configured scope is smaller.
+
+## Local Commands
+
+Install and run through core:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+./.venv/bin/python -m pip install -r requirements-dev.txt
+```
+
+For combined checks once implementation starts, run:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+./scripts/check-focused.sh
+```
+
+## Working Rules
+
+- Keep documentation-layer behavior in this module, not core.
+- Read configuration, module manifests, routes, permissions, and capability metadata through core contracts.
+- Do not import feature-module internals. Modules should contribute documentation metadata through manifests, capabilities, generated docs, or typed DTOs.
+- Prefer role-aware and configuration-aware documentation over global manuals.
+- Keep active backlog state in Gitea issues; keep durable context in repository docs and synced wiki pages.

README.md

@@ -0,0 +1,44 @@
+# govoplan-docs
+
+GovOPlaN Docs provides the documentation layer for configured GovOPlaN systems.
+
+It answers "what does this installation provide for me?" before it answers "what could the full product do?". The goal is to reduce documentation complexity by starting from installed modules, enabled configuration, tenant policy, role, route availability, and visible capabilities.
+
+## Ownership
+
+This repository owns:
+
+- backend module manifest `docs`
+- configured-system documentation indexing
+- documentation source and contribution contracts
+- role-aware and tenant-aware documentation filtering
+- evidence pages for disabled, unavailable, or optional capabilities
+- documentation route contributions and future WebUI package `@govoplan/docs-webui`
+- documentation sync/import tooling that belongs to the runtime docs layer rather than the repository maintenance scripts
+
+Core owns module discovery, configuration package loading, route registry, RBAC evaluation, capability registry, and shared WebUI shell behavior.
+
+## Documentation model
+
+The docs module should render documentation in three layers:
+
+- Configured: installed and enabled behavior that applies to the current tenant, organization, role, or route.
+- Available: installed but disabled or hidden behavior that can be enabled by configuration or permission.
+- Evidence: referenced capabilities, modules, examples, or product documentation that explain what else may be possible without making it the primary reading path.
+
+## Module integration
+
+Backend entry point:
+
+```toml
+[project.entry-points."govoplan.modules"]
+docs = "govoplan_docs.backend.manifest:get_manifest"
+```
+
+Frontend package:
+
+```text
+@govoplan/docs-webui
+```
+
+Platform module manifests, configuration packages, release catalogs, and governance rules are documented in `govoplan-core/docs/`.

docs/DOCS_BACKLOG.md

@@ -0,0 +1,27 @@
+# Docs Backlog
+
+## P1 Immediate
+
+- [ ] Define the `docs` backend manifest, permissions, module metadata, and route contribution.
+- [ ] Define documentation source DTOs for manifests, routes, capabilities, policies, configuration packages, and wiki-backed sources.
+- [ ] Implement configured, available, and evidence classification for documentation entries.
+- [ ] Add API routes for current-context documentation lookup and source inspection.
+- [ ] Create focused tests for role-aware and configuration-aware documentation filtering.
+
+## P2 Module Integration
+
+- [ ] Define module manifest fields for documentation contributions.
+- [ ] Define capability metadata fields that the docs module can render without importing provider internals.
+- [ ] Integrate release catalog and configuration package descriptions as documentation sources.
+- [ ] Link repository docs and synced wiki pages as durable evidence sources.
+
+## P2 WebUI
+
+- [ ] Build the documentation browser route contribution and navigation metadata.
+- [ ] Build configured-system, available-feature, and evidence views.
+- [ ] Build route-aware help entry points from the shared WebUI shell.
+
+## P3 Governance
+
+- [ ] Document ownership rules for runtime docs, repository docs, Gitea wiki pages, and active Gitea issues.
+- [ ] Document privacy and permission boundaries for role-aware documentation.

docs/DOCUMENTATION_LAYER_CONCEPT.md

@@ -0,0 +1,123 @@
+# Documentation Layer Concept
+
+## Purpose
+
+GovOPlaN Docs provides a documentation layer that starts with the configured system instead of the full theoretical product. Users should first see the modules, routes, permissions, policies, workflows, and operational choices that are actually available in their installation.
+
+Only after that should the documentation provide evidence about what else might be possible: installed-but-disabled features, optional modules, extension points, product capabilities, or examples from other configurations.
+
+## Problem
+
+Traditional product documentation describes the full system. That creates avoidable complexity in configurable public-sector platforms because most users only need a slice of the system:
+
+- their tenant
+- their organization
+- their role
+- installed modules
+- enabled route contributions
+- enabled policy and configuration packages
+- visible capabilities
+
+When documentation begins with everything, the user must filter out unavailable features themselves. The docs module should invert that flow.
+
+## Documentation Layers
+
+The module should classify documentation into three layers.
+
+### Configured
+
+Configured documentation describes what is active for the current system and actor. It should be the default view.
+
+Inputs may include:
+
+- installed module manifests
+- enabled routes and navigation contributions
+- current tenant and organization context
+- effective permissions and roles
+- configuration packages
+- policy sources
+- capability registry entries
+- release catalog and module dependency metadata
+
+### Available
+
+Available documentation describes behavior that exists in the installation but is not currently visible or enabled for the actor.
+
+Examples:
+
+- a module is installed but hidden by tenant configuration
+- a route exists but the actor lacks permission
+- a policy can be enabled by an administrator
+- a capability provider exists but no local binding is configured
+
+This layer should explain the enabling condition without exposing sensitive data.
+
+### Evidence
+
+Evidence documentation describes possibilities beyond the configured surface.
+
+Examples:
+
+- optional modules not installed here
+- product documentation and examples
+- capability contracts that a module could provide
+- migration or rollout notes
+- links to wiki pages and durable repository docs
+
+Evidence should be discoverable, but it should not be the primary reading path for users trying to operate the current system.
+
+## Source Model
+
+The docs module should consume documentation sources through explicit contracts:
+
+- module manifest documentation metadata
+- route metadata and page-level help references
+- capability metadata
+- configuration-package descriptions
+- release catalog entries
+- repository docs mirrored into Gitea wiki pages
+- manually curated admin documentation pages
+
+Feature modules should contribute documentation metadata without the docs module importing their internals.
+
+## Rendering Model
+
+The runtime docs UI should be context-aware:
+
+- tenant-aware
+- organization-aware where relevant
+- role-aware
+- route-aware
+- module-aware
+- configuration-aware
+
+The same documentation source may render differently for an operator, module administrator, tenant administrator, or end user.
+
+The UI should make the current context explicit enough to avoid confusion, but it should avoid turning every page into a full configuration report. A compact "why am I seeing this?" explanation is usually enough.
+
+## Governance
+
+Durable context belongs in repository docs and synced wiki pages. Active work belongs in Gitea issues. Runtime documentation should link both where helpful, but it should distinguish stable explanation from changing backlog state.
+
+Documentation sources should be auditable when they affect compliance, operator procedure, or policy explanation. Configuration-derived documentation should identify the source configuration package or policy source where possible.
+
+## First Implementation Shape
+
+The first implementation should define:
+
+- the `docs` module manifest
+- documentation source DTOs
+- a source registry capability
+- a configured/available/evidence classifier
+- a minimal API for current-context documentation
+- a WebUI route contribution for the documentation browser
+
+The first UI can be simple:
+
+- configured modules
+- visible routes
+- active policies
+- available-but-disabled evidence
+- source links to wiki or repository docs
+
+Once the source model is stable, feature modules can add richer documentation contributions through their manifests and capabilities.

docs/gitea-labels.json

@@ -0,0 +1,404 @@
+[
+  {
+    "name": "type/bug",
+    "color": "d73a4a",
+    "description": "A reproducible defect, regression, or incorrect behavior.",
+    "exclusive": true
+  },
+  {
+    "name": "type/feature",
+    "color": "0e8a16",
+    "description": "New user-visible behavior or platform capability.",
+    "exclusive": true
+  },
+  {
+    "name": "type/task",
+    "color": "1d76db",
+    "description": "Implementation, maintenance, migration, or operational work.",
+    "exclusive": true
+  },
+  {
+    "name": "type/debt",
+    "color": "fbca04",
+    "description": "Cleanup, refactoring, risk reduction, or deferred engineering work.",
+    "exclusive": true
+  },
+  {
+    "name": "type/docs",
+    "color": "5319e7",
+    "description": "Documentation, process, or developer workflow work.",
+    "exclusive": true
+  },
+  {
+    "name": "priority/p0",
+    "color": "b60205",
+    "description": "Immediate stop-the-line priority.",
+    "exclusive": true
+  },
+  {
+    "name": "priority/p1",
+    "color": "d93f0b",
+    "description": "High priority for the next focused work window.",
+    "exclusive": true
+  },
+  {
+    "name": "priority/p2",
+    "color": "fbca04",
+    "description": "Normal planned priority.",
+    "exclusive": true
+  },
+  {
+    "name": "priority/p3",
+    "color": "c2e0c6",
+    "description": "Low priority or opportunistic cleanup.",
+    "exclusive": true
+  },
+  {
+    "name": "status/triage",
+    "color": "d4c5f9",
+    "description": "Needs review, ownership, priority, or acceptance criteria.",
+    "exclusive": true
+  },
+  {
+    "name": "status/ready",
+    "color": "0e8a16",
+    "description": "Ready for implementation.",
+    "exclusive": true
+  },
+  {
+    "name": "status/in-progress",
+    "color": "0052cc",
+    "description": "Currently being worked.",
+    "exclusive": true
+  },
+  {
+    "name": "status/blocked",
+    "color": "b60205",
+    "description": "Cannot progress without a decision, dependency, credential, or external change.",
+    "exclusive": true
+  },
+  {
+    "name": "status/needs-info",
+    "color": "f9d0c4",
+    "description": "Needs clarifying input before implementation can proceed safely.",
+    "exclusive": true
+  },
+  {
+    "name": "module/access",
+    "color": "0e8a16",
+    "description": "GovOPlaN access, identity, authentication, RBAC, and administration behavior.",
+    "exclusive": false
+  },
+  {
+    "name": "module/addresses",
+    "color": "5319e7",
+    "description": "GovOPlaN Addresses module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/admin",
+    "color": "006b75",
+    "description": "GovOPlaN Admin module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/appointments",
+    "color": "d876e3",
+    "description": "GovOPlaN Appointments module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/audit",
+    "color": "0e8a16",
+    "description": "GovOPlaN Audit module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/calendar",
+    "color": "bfd4f2",
+    "description": "GovOPlaN Calendar module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/campaign",
+    "color": "d876e3",
+    "description": "GovOPlaN campaign module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/cases",
+    "color": "1d76db",
+    "description": "GovOPlaN Cases module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/connectors",
+    "color": "c2e0c6",
+    "description": "GovOPlaN Connectors module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/core",
+    "color": "0052cc",
+    "description": "GovOPlaN core runner, shared primitives, shell, or extension points.",
+    "exclusive": false
+  },
+  {
+    "name": "module/dms",
+    "color": "c5def5",
+    "description": "GovOPlaN Dms module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/docs",
+    "color": "5319e7",
+    "description": "GovOPlaN documentation layer behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/erp",
+    "color": "fef2c0",
+    "description": "GovOPlaN Erp module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/files",
+    "color": "006b75",
+    "description": "GovOPlaN files module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/fit-connect",
+    "color": "fbca04",
+    "description": "GovOPlaN Fit Connect module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/forms",
+    "color": "f9d0c4",
+    "description": "GovOPlaN Forms module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/identity-trust",
+    "color": "d4c5f9",
+    "description": "GovOPlaN Identity Trust module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/idm",
+    "color": "0052cc",
+    "description": "GovOPlaN Idm module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/ledger",
+    "color": "5319e7",
+    "description": "GovOPlaN Ledger module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/mail",
+    "color": "5319e7",
+    "description": "GovOPlaN mail module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/notifications",
+    "color": "d876e3",
+    "description": "GovOPlaN Notifications module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/ops",
+    "color": "0e8a16",
+    "description": "GovOPlaN Ops module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/payments",
+    "color": "bfd4f2",
+    "description": "GovOPlaN Payments module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/policy",
+    "color": "d93f0b",
+    "description": "GovOPlaN Policy module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/portal",
+    "color": "1d76db",
+    "description": "GovOPlaN Portal module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/reporting",
+    "color": "c2e0c6",
+    "description": "GovOPlaN Reporting module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/search",
+    "color": "bfdadc",
+    "description": "GovOPlaN Search module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/scheduling",
+    "color": "d93f0b",
+    "description": "GovOPlaN Scheduling module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/tasks",
+    "color": "c5def5",
+    "description": "GovOPlaN Tasks module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/templates",
+    "color": "fef2c0",
+    "description": "GovOPlaN Templates module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/tenancy",
+    "color": "e4e669",
+    "description": "GovOPlaN Tenancy module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/web",
+    "color": "bfd4f2",
+    "description": "GovOPlaN public website, product page, or publication content.",
+    "exclusive": false
+  },
+  {
+    "name": "module/workflow",
+    "color": "f9d0c4",
+    "description": "GovOPlaN Workflow module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/xoev",
+    "color": "d4c5f9",
+    "description": "GovOPlaN Xoev module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/xrechnung",
+    "color": "0052cc",
+    "description": "GovOPlaN Xrechnung module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "module/xta-osci",
+    "color": "5319e7",
+    "description": "GovOPlaN Xta Osci module behavior or integration.",
+    "exclusive": false
+  },
+  {
+    "name": "area/auth",
+    "color": "bfd4f2",
+    "description": "Authentication, sessions, access bootstrap, or login behavior.",
+    "exclusive": false
+  },
+  {
+    "name": "area/tenancy",
+    "color": "bfdadc",
+    "description": "Tenant boundaries, provisioning, or tenant-scoped data behavior.",
+    "exclusive": false
+  },
+  {
+    "name": "area/rbac",
+    "color": "c5def5",
+    "description": "Permissions, roles, delegation, or authorization policy.",
+    "exclusive": false
+  },
+  {
+    "name": "area/governance",
+    "color": "fef2c0",
+    "description": "Governance policy, audit, privacy, retention, or compliance behavior.",
+    "exclusive": false
+  },
+  {
+    "name": "area/module-system",
+    "color": "bfe5bf",
+    "description": "Module discovery, manifests, capabilities, routing, or optional integrations.",
+    "exclusive": false
+  },
+  {
+    "name": "area/migrations",
+    "color": "e4e669",
+    "description": "Alembic migrations, schema bootstrap, or persistence evolution.",
+    "exclusive": false
+  },
+  {
+    "name": "area/webui",
+    "color": "1d76db",
+    "description": "Shared WebUI shell, frontend components, routing, or frontend tests.",
+    "exclusive": false
+  },
+  {
+    "name": "area/api",
+    "color": "5319e7",
+    "description": "HTTP API contracts, routers, schemas, or API smoke behavior.",
+    "exclusive": false
+  },
+  {
+    "name": "area/db",
+    "color": "0e8a16",
+    "description": "Database sessions, models, transactions, or persistence primitives.",
+    "exclusive": false
+  },
+  {
+    "name": "area/devex",
+    "color": "bfd4f2",
+    "description": "Local developer workflow, scripts, tests, tooling, or release helpers.",
+    "exclusive": false
+  },
+  {
+    "name": "area/release",
+    "color": "c2e0c6",
+    "description": "Versioning, release locks, tags, packaging, or dependency pins.",
+    "exclusive": false
+  },
+  {
+    "name": "area/docs",
+    "color": "5319e7",
+    "description": "Durable documentation and project guidance.",
+    "exclusive": false
+  },
+  {
+    "name": "area/marketing",
+    "color": "f9d0c4",
+    "description": "Public website, product messaging, publication copy, or legal page content.",
+    "exclusive": false
+  },
+  {
+    "name": "source/todo-scan",
+    "color": "cccccc",
+    "description": "Imported from inline TODO/FIXME/HACK markers by the Gitea TODO importer.",
+    "exclusive": false
+  },
+  {
+    "name": "source/backlog-import",
+    "color": "bfdadc",
+    "description": "Imported from markdown backlog, roadmap, plan, or TODO files.",
+    "exclusive": false
+  },
+  {
+    "name": "codex/ready",
+    "color": "0e8a16",
+    "description": "Suitable for Codex to pick up with the existing issue context.",
+    "exclusive": false
+  },
+  {
+    "name": "codex/needs-human",
+    "color": "f9d0c4",
+    "description": "Needs an explicit human decision before Codex should implement.",
+    "exclusive": false
+  }
+]