Document the current Policy Workbench architecture

Create developer_manual/architecture/policy-workbench.rst and update the “Where to go next” section in developer_manual/architecture.rst; check the manual toctree as needed. Start with LibreSign/libresign/AGENTS.md, the architecture page, and the listed backend, frontend, and test paths to verify each claim about current behavior. Build and review the rendered manual, confirm links resolve, and include screenshots in the PR; done means all required sections describe only verified behavior and the documented validation passes.

Goal

Document the current LibreSign Policy Workbench architecture so a contributor can understand how policies are defined, resolved, delegated, enforced and represented in the frontend without reconstructing the design from source code.

This issue documents behavior that already exists.

Do not design AI policies, change Policy Workbench behavior, or make product decisions in this issue.

This documentation will be used as factual input by LibreSign/libresign#9054.

Why this is a good first issue

The architecture already exists in code and tests.

The contributor does not need to decide:

• how Policy Workbench should work;
• which scopes LibreSign should support;
• how delegation should behave;
• how AI policies should be modeled;
• whether frontend or backend owns authorization.

The task is to extract, verify and organize existing behavior using the sources listed below.

If behavior cannot be confirmed from code/tests, do not guess. Add a comment to this issue with the exact unresolved point.

Documentation destination

Create:

developer_manual/architecture/policy-workbench.rst

Do not move or rename:

developer_manual/architecture.rst

Update developer_manual/architecture.rst so its "Where to go next" section links to the new page.

Update the developer manual toctree only as needed so Sphinx includes the page.

Do not create a new top-level manual or reorganize unrelated documentation.

Sources to inspect

Architecture guidance

Start with:

• LibreSign/libresign/AGENTS.md
• developer_manual/architecture.rst

The application repository is the source of truth for implementation details.

Backend

Inspect at least:

• lib/Service/Policy/
• lib/Service/Policy/Provider/

Identify:

• where policy definitions live;
• how policy keys are represented;
• how scopes are resolved;
• how effective values are computed;
• how delegation/editability metadata is represented;
• where backend enforcement belongs.

Frontend

Inspect at least:

• src/views/Settings/PolicyWorkbench/
• src/views/Settings/PolicyWorkbench/settings/
• src/views/Preferences/personalPreferenceVisibility.ts
• src/store/policies.ts if relevant to the current flow.

Identify:

• how backend policy metadata reaches the UI;
• where policy-specific frontend models/editors live;
• how editability/delegation is represented;
• how personal preferences relate to Policy Workbench.

Do not describe frontend checks as authorization.

Tests

Use existing tests to confirm behavior.

Inspect relevant files under:

• tests/php/
• src/tests/
• playwright/

Also inspect:

• playwright/support/policy-workbench-rules.ts

Use tests to verify claims about scope, delegation, effective values and frontend behavior.

Required page structure

The new page must use this structure.

1. What Policy Workbench is

Write 1-2 short paragraphs explaining:

• why LibreSign uses policies;
• that policies centralize configurable behavior;
• that backend policy resolution/enforcement is authoritative.

Do not begin with class names.

2. Policy scopes

Document the currently supported scopes.

Explain the actual system/group/user relationship found in code and tests.

Use one short conceptual example if useful.

Do not invent AI-specific examples.

3. Effective policy resolution

Explain:

• what an effective policy value means;
• how lower scopes interact with higher scopes;
• where the backend resolves the final value.

Only describe behavior confirmed in code/tests.

4. Delegation and customization

Explain:

• how a higher scope determines whether lower scopes may customize a policy;
• editability/delegation metadata;
• what the frontend may display versus what the backend enforces.

5. Backend enforcement

Explain the security boundary:

• backend is the source of truth;
• frontend metadata improves UX but does not grant permission;
• missing/failed policy information must not be treated as permission unless current code explicitly says otherwise.

Reference relevant implementation areas without turning the page into a class inventory.

6. Frontend representation

Explain:

• definition/model/editor responsibilities;
• where shared Policy Workbench behavior ends and policy-specific UI begins;
• how the frontend consumes backend-owned policy metadata.

7. Compound policies

Document compound/parent-child policy behavior only if it exists in the current implementation.

Explain the concept first, then point to the relevant source areas.

8. Personal preferences

Explain how personal preference visibility/customization relates to Policy Workbench where current code supports it.

Do not claim every policy has a personal preference.

9. Adding a new policy

Document the existing extension path for contributors.

Describe which backend and frontend responsibilities normally need to be considered and which tests should be used as examples.

Do not create a new policy in this issue.

10. Testing expectations

Explain which test layers protect:

• backend policy definition/resolution;
• frontend model/editor behavior;
• end-to-end Policy Workbench behavior.

Point to representative existing tests.

11. Related architecture

Add cross-references back to:

• the main architecture page;
• testing/development documentation where relevant.

Do not duplicate those pages.

Writing requirements

Write for a developer who knows PHP/TypeScript but has never worked on LibreSign Policy Workbench.

Use these rules:

• explain concepts before classes/files;
• use present tense for current behavior;
• use direct, declarative language;
• do not narrate how you researched the feature;
• do not write "we discovered", "during implementation", or similar history;
• do not document roadmap behavior as implemented;
• use file/class names only when they help a contributor locate an extension point;
• every architectural claim must be traceable to current code, tests or repository guidance;
• prefer cross-references over repeating content from another documentation page;
• keep examples synthetic and free of personal/customer data.

Evidence rule

Before writing each section, confirm the behavior from at least one of:

• implementation code;
• automated tests;
• repository architecture guidance.

When code and tests appear to disagree:

1. do not choose one behavior yourself;
2. do not "fix" production code in this PR;
3. comment on this issue with the conflicting evidence;
4. wait for maintainer clarification before documenting that point.

Screenshots

Because this PR changes rendered documentation, the pull request must include screenshots of the rendered page. Repository-wide contribution guidance for this rule is tracked by #46; this issue's screenshot requirement applies even if #46 is still open.

For this page:

• include at least one screenshot showing the new page title, introductory section and navigation context;
• if the page is too long to review in one readable screenshot, add additional focused screenshots;
• screenshots are PR review evidence and must not be committed into the manual unless the documentation itself genuinely needs an image.

Do not include sensitive information.

Out of scope

Do not:

• add or modify production policies;
• change Policy Workbench code;
• design AI policies;
• define future policy keys;
• refactor backend/frontend architecture;
• change system/group/user semantics;
• reorganize unrelated developer documentation;
• copy large source-code excerpts into the manual.

Validation

Before opening the PR:

1. build the developer manual using the repository's documented build flow;
2. verify the new page is reachable from the developer architecture documentation;
3. verify internal Sphinx links resolve;
4. verify every implementation path/class named in the page still exists;
5. review the rendered output, not only the RST source;
6. include the required screenshots in the PR description.

Done when

• developer_manual/architecture/policy-workbench.rst exists.
• The main architecture page links to it.
• Purpose, scopes, effective values, delegation, enforcement, frontend representation, compound policies, preferences and extension path are documented.
• The page describes only behavior verified from current code/tests.
• No AI-specific future behavior is presented as implemented.
• Relevant testing layers and representative tests are referenced.
• Sphinx build/checks pass.
• The PR includes screenshots of the rendered documentation.