Restructure agentic guideline files

.claude/launch.json

@@ -0,0 +1,39 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "vue-demo",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "vue", "run", "dev"],
+      "port": 5173
+    },
+    {
+      "name": "vue-storybook",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "vue", "run", "storybook"],
+      "port": 6006
+    },
+    {
+      "name": "django-demo",
+      "runtimeExecutable": "django/.venv/bin/python",
+      "runtimeArgs": ["django/manage.py", "runserver"],
+      "port": 8000
+    },
+    {
+      "name": "bff-flask",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": [
+        "run",
+        "--project",
+        "bff",
+        "flask",
+        "--app",
+        "bff/bff.py",
+        "run",
+        "--port",
+        "5022"
+      ],
+      "port": 5022
+    }
+  ]
+}

.gitignore

@@ -7,3 +7,4 @@
 django/docs/source/api/*
 django/docs/output/**/*
 .env
+*/__pycache__

AGENTS.md

@@ -1,56 +1,62 @@
-# N-SIDE WeFa – Agent Guide
+# N-SIDE WeFa - Agent Guide
 
-## Project Snapshot
-- WeFa (Web Factory) ships two publishable packages: `django/` contains the `nside-wefa` Django toolkit, `vue/` contains the `@nside/wefa` Vue 3 component library.
-- Goal: provide production-ready auth, legal-consent, other backend packages, and UI building blocks so product teams can assemble full-stack experiences quickly.
-- Primary technologies: Python 3.12+, Django 5.2 + Django REST Framework, Vitest + Playwright, Vue 3 + PrimeVue + Tailwind 4.
+## Purpose
 
-## Repository Layout & Key Docs
-- `README.md` – top-level overview; defer to `django/README.md` and `vue/README.md` for workspace specifics.
-- `django/` – reusable apps (`nside_wefa.common`, `.authentication`, `.legal_consent`, etc) plus `demo/` project and pytest setup.
-- `vue/` – component library, demo playground, Storybook, scripts (e.g. `wefa-install`), and AI guidance (`scripts/files/copilot-instructions.md`).
-- Contribution guides: `django/CONTRIBUTE.md` & `vue/CONTRIBUTE.md` define environment setup, quality gates, and release discipline.
+This file gives Codex durable repository context. Keep it concise: put shared rules here, put workspace-specific rules in nested `AGENTS.md` files, and move repeatable task workflows into skills.
+
+Codex loads AGENTS instructions from the repository root down to the current working directory. Later files are more specific, so prefer plain nested `AGENTS.md` files for additive guidance. Use `AGENTS.override.md` only when intentionally replacing broader guidance.
+
+## Repository Map
+
+- `django/` publishes the `nside-wefa` Django toolkit with reusable apps under `nside_wefa/` and the `demo/` validation project.
+- `vue/` publishes the `@nside/wefa` Vue 3 library, demo app, Storybook docs, CLI helpers, and generated OpenAPI demo clients.
+- `bff/` provides the Flask backend-for-frontend for OAuth login/logout/session checks and proxying backend REST calls.
+- `scripts/` contains repository automation, especially the version orchestrator used to keep package versions aligned.
+- `.github/workflows/` is the source of truth for CI-equivalent validation commands.
+
+## Technology Baseline
+
+- Python workspaces target Python 3.12+ and use `uv`, pytest, Ruff, mypy, and security checks.
+- `django/` targets modern Django, Django REST Framework, Simple JWT, drf-spectacular, and Hatchling packaging.
+- `bff/` uses Flask, Authlib, encrypted token cookies, Docker, and generated OpenAPI documentation.
+- `vue/` uses Vue 3, Vite, TypeScript, PrimeVue, Tailwind 4, Pinia, Vue I18n, TanStack Query, Vitest, Storybook, and Playwright.
 
 ## Instruction Routing
-- For frontend work inside `vue/` (components, containers, stories/docs, translations, tests), use the `$wefa-vue-frontend` skill defined at `skills/wefa-vue-frontend/SKILL.md`.
-- For work inside `django/`, use the backend guidance in this file until a dedicated `django/AGENTS.md` is introduced.
-- For cross-cutting work (API + UI), follow this file for shared expectations and apply the `wefa-vue-frontend` skill for the frontend part.
-
-## Core Engineering Principles
-- **Convention over configuration**: align with provided settings helpers (`NSIDE_WEFA` for Django and documented Vue defaults) before introducing bespoke wiring.
-- **Type safety & documentation**: keep Python and TypeScript hints accurate; add comments only for non-obvious logic; update relevant docs whenever behaviour changes.
-- **Tests as gatekeepers**: extend existing suites when behaviour changes; no feature lands without matching tests unless explicitly justified.
-
-## Backend Playbook (`django/`)
-- **App structure**: extend existing apps (`nside_wefa.authentication`, `.legal_consent`, `.common`, etc) unless a new domain warrants a standalone package. Mirror current layout: `apps.py`, `checks.py`, `models/`, `serializers.py`, `urls.py`, `views/`, `tests/`, `README.md`.
-- **Settings contract**: all configuration flows through the `NSIDE_WEFA` dict. When adding options, document in `django/README.md`, add system checks in `checks.py`, and ensure defaults keep migrations optional.
-- **APIs & serializers**: follow DRF patterns already present; keep authentication utilities DRY by placing shared logic under `utils/`. Expose URLs through `include('nside_wefa.<app>.urls')` and cover them in tests.
-- **Testing & quality**: use pytest with Django (`pytest` or `python manage.py test`) plus coverage when needed. Run `ruff format .`, `ruff check .`, and `mypy nside_wefa/` before submission. Demo project (`django/demo`) is available for manual validation.
-
-## Shared Workflow Expectations
-- Stay within the workspace toolchain: `uv`/pip + Hatchling builds for Django, npm scripts + Vite for Vue.
-- Keep lockfiles consistent with the package manager in use (`uv.lock`, `package-lock.json`).
-- Maintain documentation parity: adjust relevant READMEs, MDX docs, or changelog entries (once introduced) whenever behaviour changes.
-- For cross-cutting features, coordinate backend API shape first, then wire the frontend through the generated clients/composables.
-
-## Decision Checklists
-- **Before shipping backend change**:
-  - [ ] Update/extend system checks and settings docs.
-  - [ ] Provide migrations only when required and reversible.
-  - [ ] Add pytest coverage for new branches/edge cases.
-- **Before opening a PR**:
-  - [ ] Run required backend lint/format/test commands.
-  - [ ] Update backend docs/demo snippets as needed.
-  - [ ] Document breaking changes and version impacts.
-
-## Quick Command Reference
-- Backend install: `cd django && pip install -e .[dev]` (or `uv sync --all-extras`)
-- Backend tests: `cd django && pytest`
-- Backend lint/type: `cd django && ruff check . && ruff format --check && mypy nside_wefa/`
-
-## When in Doubt
-- Re-read the relevant `README.md` and `CONTRIBUTE.md` before altering flows.
-- Trace existing backend implementations (e.g., `nside_wefa/legal_consent`) to mirror patterns.
-- Surface open questions early (e.g., new authentication modes) so design/system owners can confirm direction.
-
-Following this guide keeps contributions aligned with the existing architecture, ensures compliance with the WeFa component hierarchy, and preserves release quality across both Django and Vue packages.
+
+- For `django/` work, read `django/AGENTS.md`, `django/README.md`, and `django/CONTRIBUTE.md`.
+- For `vue/` work, read `vue/AGENTS.md`, `vue/README.md`, and `vue/CONTRIBUTE.md`; use `$wefa-vue-frontend` for component, container, Storybook, i18n, demo, and frontend test work.
+- For TanStack Query work in `vue/`, also use `$wefa-tanstack-query`.
+- For `bff/` work, read `bff/AGENTS.md` and `bff/README.md`.
+- For `scripts/` work, read `scripts/AGENTS.md`.
+- For cross-cutting changes, coordinate backend/API shape first, then update consumers and documentation in the affected workspaces.
+
+The current repository skills live under `skills/`. A later cleanup should migrate shared Codex skills to official repository discovery under `.agents/skills`, but do not do that as part of AGENTS-only edits unless explicitly requested.
+
+## Shared Engineering Rules
+
+- Explore first: inspect existing implementations, neighboring files, docs, and CI before designing changes.
+- Prefer existing conventions and helpers over new bespoke wiring.
+- Preserve public APIs unless the task explicitly asks for a breaking change; document behavior changes where consumers will notice them.
+- Keep Python and TypeScript types accurate. Avoid broad casts, silent fallbacks, and broad exception handling.
+- Keep user-facing copy localized in frontend code and documented in the relevant README, MDX, or package docs.
+- Add or update tests when behavior changes. If validation is skipped, state exactly why.
+- Do not hand-edit generated artifacts unless the workspace guide explicitly allows it.
+- Do not commit secrets. Treat `.env` files, OAuth credentials, tokens, and generated local IDE/cache files as local-only.
+
+## Versioning And Releases
+
+- The monorepo uses one shared version across `django/`, `vue/`, and `bff/`.
+- Use `python3 scripts/wefa_version.py` from the repository root for version changes.
+- Prefer `--dry-run` before version changes; do not manually edit per-package version fields unless repairing the orchestrator itself.
+- Keep lockfiles consistent with the package manager used in the branch: `uv.lock` for Python workspaces and `package-lock.json` for npm.
+
+## Validation Expectations
+
+- Run the smallest relevant checks while iterating, then run the workspace's CI-equivalent commands before handoff when feasible.
+- Documentation-only AGENTS changes do not require product test suites, but they should pass basic markdown/content sanity checks.
+- For reviews, prioritize bugs, behavior regressions, missing tests, security risks, and docs drift before style suggestions.
+
+## Compatibility Notes
+
+- Codex guidance should come from `AGENTS.md` files and skills, not generated assistant instruction artifacts.
+- Keep AGENTS files compact. Link to workspace docs rather than copying full manuals so the combined instruction chain stays below Codex's default 32 KiB project-doc size limit.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

bff/AGENTS.md

@@ -0,0 +1,48 @@
+# WeFa BFF - Agent Guide
+
+## Scope
+
+This file applies to the Flask backend-for-frontend in `bff/`. The service handles OAuth login/logout/session checks, encrypted token cookies, health endpoints, OpenAPI generation, and proxying backend REST calls.
+
+Read `bff/README.md` before changing environment contracts, auth/session behavior, OpenAPI output, Docker behavior, or deployment-facing docs.
+
+## Security And Configuration Rules
+
+- Never commit `.env`, OAuth credentials, token values, cookie encryption keys, or local IDE/cache artifacts.
+- Keep `.env.example` and README documentation in sync with required and optional settings.
+- Required settings should fail fast at startup when missing or blank.
+- Preserve production security defaults unless explicitly directed otherwise: HttpOnly token cookies, secure cookie settings, strict SameSite behavior, PKCE verifier/state handling, and explicit callback error handling.
+- Token cookies are derived from `SESSION_COOKIE_NAME`; changes to names, payload split behavior, encryption, or expiry semantics need tests and rollout notes.
+- Do not add broad proxy fallbacks that hide backend failures. Surface upstream errors consistently with existing route behavior.
+
+## Implementation Rules
+
+- Keep route handlers in `bff_app/routes/` and reusable behavior in `bff_app/services/` or `bff_app/settings.py`.
+- Preserve the OpenAPI generator as the source of truth for `bff_app/openapi/openapi.yaml`.
+- Use `uv` for dependency and command execution in this workspace.
+- Update Docker and README instructions together when runtime ports, environment variables, or startup commands change.
+
+## Tests And OpenAPI
+
+- Add or update tests under `tests/` for auth redirects, callback errors, session behavior, token-cookie behavior, proxying, settings validation, and OpenAPI generation.
+- Regenerate OpenAPI intentionally, then check for drift.
+- Use narrow pytest runs while iterating, then the CI-equivalent checks before handoff when feasible.
+
+## Validation Commands
+
+Run from `bff/` unless noted:
+
+```bash
+uv run pytest -q
+uv run python -m bff_app.openapi.generate --check --output bff_app/openapi/openapi.yaml
+uvx pysentry-rs --config .pysentry.toml .
+```
+
+For manual local validation:
+
+```bash
+FLASK_RUN_PORT=5022 uv run flask --app bff.py run
+docker-compose up --build
+```
+
+Only run server or Docker commands when manual behavior verification is needed.

bff/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

django/AGENTS.md

@@ -0,0 +1,48 @@
+# WeFa Django - Agent Guide
+
+## Scope
+
+This file applies to the Django toolkit in `django/`. The package publishes `nside-wefa` and contains reusable apps under `nside_wefa/` plus the `demo/` project used for local and CI validation.
+
+Read `django/README.md` and `django/CONTRIBUTE.md` before changing public behavior, settings, migrations, or release-facing docs.
+
+## Architecture Rules
+
+- Extend existing apps when the domain fits: `common`, `authentication`, `legal_consent`, `locale`, `audit`, `attachments`, `admin_theme`, or `utils`.
+- Mirror the existing app layout: `apps.py`, `checks.py`, `models/`, `serializers.py`, `urls.py`, `views/`, `tests/`, and app-level README files where applicable.
+- Keep all project configuration under the `NSIDE_WEFA` settings dictionary. New settings need defaults, Django system checks, tests, and README documentation.
+- `nside_wefa.common` is foundational and should remain before dependent WeFa apps in `INSTALLED_APPS` examples.
+- Prefer Django and DRF conventions over custom framework code. Put shared authentication or request helpers under the nearest `utils/` module.
+- Expose app routes through `include("nside_wefa.<app>.urls")` and cover URL/API behavior in tests.
+
+## Data, Migrations, And Checks
+
+- Add migrations only when model state changes. Keep them reversible unless Django cannot reasonably reverse the operation.
+- Run `python manage.py makemigrations --check --dry-run` when model or field definitions change.
+- Run `python manage.py check` or targeted system-check tests when changing settings contracts.
+- Preserve existing data semantics for legal consent, audit events, locale preferences, and authentication unless the task explicitly defines a migration path.
+- Audit-related changes must preserve append-only expectations and document any tamper-evident or retention behavior changes.
+
+## Documentation And Tests
+
+- Update `django/README.md`, app READMEs, or demo snippets when configuration, URLs, APIs, or behavior changes.
+- Add pytest coverage for new branches, validation checks, serializers, views, management commands, and migrations where relevant.
+- Use the demo project for manual verification when behavior depends on Django settings or installed app ordering.
+
+## Validation Commands
+
+Run from `django/` unless noted:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+DJANGO_SETTINGS_MODULE=demo.settings uv run mypy --install-types --non-interactive .
+python manage.py makemigrations --check --dry-run
+python manage.py migrate --plan
+python manage.py migrate --noinput
+uv run pytest --cov-config=.coveragerc --cov-report xml --cov .
+uvx pysentry-rs --config .pysentry.toml .
+uv run bandit -c pyproject.toml -r nside_wefa -n 3 -l
+```
+
+If running a smaller subset, choose the narrowest command that exercises the changed app and state what remains unrun.

django/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

scripts/AGENTS.md

@@ -0,0 +1,35 @@
+# WeFa Scripts - Agent Guide
+
+## Scope
+
+This file applies to repository automation under `scripts/`, including the shared version orchestrator.
+
+Read the root `README.md` release/versioning section before changing version automation or release-facing behavior.
+
+## Versioning Rules
+
+- The monorepo uses one shared version across `django/`, `vue/`, and `bff/`.
+- `scripts/wefa_version.py` is the owner for version reads, checks, bumps, and explicit sets.
+- Do not manually edit per-package version fields in `django/pyproject.toml`, `vue/package.json`, `vue/package-lock.json`, or `bff/pyproject.toml` unless the task is to repair the orchestrator or generated version state.
+- Prefer `python3 scripts/wefa_version.py <command> --dry-run` before commands that mutate version files.
+- Preserve SemVer input rules and PEP 440 normalization for Python project files.
+- Keep prerelease support limited to the identifiers documented in the root README unless the release policy changes.
+
+## Implementation Rules
+
+- Keep automation deterministic, non-interactive by default, and safe to run from CI.
+- Use explicit errors for inconsistent version state instead of silently normalizing unexpected values.
+- Update root README release/versioning docs when command behavior or supported version formats change.
+- Avoid adding dependencies for simple automation; if a dependency is necessary, document why.
+
+## Validation Commands
+
+Run from the repository root:
+
+```bash
+python3 -m unittest discover -s scripts -p 'test_*.py'
+python3 scripts/wefa_version.py show
+python3 scripts/wefa_version.py check --expect "$(python3 scripts/wefa_version.py show)"
+```
+
+For mutating version command changes, also run representative `--dry-run` bump and set commands before any real mutation.

scripts/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md