govoplan-core/AGENTS.md

GovOPlaN Codex Guide

Scope

This repository is the platform runner and shared core for GovOPlaN. It owns the server entry point, database/session primitives, auth, tenancy, RBAC, governance, module discovery, migrations, shared WebUI shell, and generic WebUI components.

Sibling module repositories usually used with this repo:

• /mnt/DATA/git/govoplan-access
• /mnt/DATA/git/govoplan-files
• /mnt/DATA/git/govoplan-mail
• /mnt/DATA/git/govoplan-campaign

Keep module-specific behavior in the owning module. Core may expose stable extension points, capabilities, and shared components, but should not directly import module WebUI pages or require optional module packages for core-only startup.

Local Commands

Use targeted commands first:

cd /mnt/DATA/git/govoplan-core
/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver --smoke --no-reload
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_module_system
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_mailbox_message_listing_reports_total_count

For WebUI checks:

cd /mnt/DATA/git/govoplan
./devkit doctor --repo core
./devkit check --profile ui --repo core --dry-run
./devkit check --profile ui --repo core

For an individually selected component batch (one compilation):

cd /mnt/DATA/git/govoplan-core/webui
npm run test:components -- mail-components page-layout
npm run test:module-capabilities
npm run test:module-permutations

Run the consolidated focused check when a change touches module discovery, optional integrations, shared mail components, or mailbox listing:

cd /mnt/DATA/git/govoplan
./devkit check --profile full

Working Rules

• Prefer rg, sed, and targeted tests over broad recursive scans or full builds.
• Avoid DataGrid changes unless explicitly requested; it is intentionally brittle and has known deferred work.
• Do not add module-to-module imports for optional integrations. Use core registry/capability/module metadata paths.
• Treat documentation as part of every behavior change. Update the owning module's manifest-driven DocumentationTopic contributions for each affected user and administrator workflow, setting, permission, limitation, and operational consequence. Feature modules own this content; govoplan-docs projects it and must not import feature internals.
• Keep a static user and administrator documentation baseline in every module manifest, even when richer configured-state topics come from documentation_providers. Run /mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py after changing a manifest or module behavior.
• Treat Gitea issues as the canonical backlog and state log. Treat Gitea wiki pages as durable project context mirrored from repository and product docs. Use docs/GITEA_ISSUES.md for labels, templates, TODO import, wiki sync, and Codex issue updates.
• Do not keep generated WebUI test folders in git status; they should be ignored and removable.
• Do not start persistent dev servers unless the user asks.