tibi-svelte-starter/.agents/skills/permissions-and-editor-workflows/SKILL.md

---
name: permissions-and-editor-workflows
description: Design safe editor workflows with current tibi-server permissions and Nova authoring patterns. Covers collection permissions, field-level readonly/hidden rules, roles, tokens, and how admin UX should reflect real editorial boundaries.
---

# permissions-and-editor-workflows

## When to use this skill

Use this skill when:

- A project needs more than one editor/admin role
- Collections or fields should be restricted by role or token
- You need readonly/hidden field logic for real editorial workflows
- You want Nova UX to reflect actual server-side permissions instead of pretending every field is editable

## Goal

The goal is to design permissions as part of the editorial workflow, not as a last-minute access check.

On this stack, permissions affect:

- API methods
- field visibility
- field editability
- collection visibility
- token-based integrations
- admin usability

## Source of truth

Use these sources when implementing or reviewing permissions:

- `tibi-server/docs/17-field-level-permissions.md`
- `tibi-server/docs/05-authentication.md`
- relevant collection YAML files
- `tibi-admin-nova/types/admin.d.ts`

## Permission layers

At minimum, reason about permissions on these levels:

- collection methods (`get`, `post`, `put`, `delete`)
- field-level `readonlyFields`
- field-level `hiddenFields`
- field-definition overrides (`readonly`, `hidden`)
- dynamic eval-based field rules
- collection `meta.hide` for sidebar visibility

Do not flatten all of this into one vague notion of “editor access”.

**Custom role names:** Permission set keys in collection/action YAML are arbitrary strings. You can define any role name (e.g. `editor`, `reviewer`, `publisher`, `seo-manager`) and assign users with matching permissions. Combined with org/team membership (see `tibi-server/docs/18-orgs-teams.md`), this enables fine-grained editorial workflows beyond the built-in `public` and `user` roles.

### The 3-layer cascade model

Field-level permissions follow a strict 3-layer cascade:

1. **Collection-Level** (`collection.readonlyFields`, `collection.hiddenFields`): Base set applied to all permission sets.
2. **PermissionSet-Level** (`permissions.<role>.readonlyFields`, `permissions.<role>.hiddenFields`): Adds to or removes from the collection-level set. Prefix a field with `-` to negate (e.g. `-createdBy` removes it from the effective set).
3. **Field-Definition Override** (`field.readonly`, `field.hidden`): Absolute override — `true` forces the field into the set, `false` forces it out regardless of upper layers.

**Important:** Field-definition `readonly`/`hidden` also supports **eval expressions** (JS) for per-document dynamic evaluation. Eval rules are evaluated in a separate phase after the static cascade (Phase 1 = static cascade, Phase 2 = per-document eval). Admin role (role=0) bypasses all field-level restrictions.

See `tibi-server/docs/17-field-level-permissions.md` for the full reference with examples and eval expression context variables (`$`, `$this`, `$auth`, `$method`, `$project`, `$namespace`).

## Collection-level workflow design

Before implementing permissions, define who does what.

Typical roles/workflows:

- public readers
- editors creating and updating content
- reviewers or restricted staff
- admins configuring structure and sensitive fields
- token-based integrations

Then map those responsibilities to explicit permission sets.

## Field-level permissions

Current tibi-server field permissions are strong and should be used deliberately.

Important behavior:

- `readonlyFields`: writes fail with `400` if those fields are sent
- `hiddenFields`: writes fail with `400`, reads strip the fields from responses
- field-level `readonly` / `hidden` can override or dynamically extend behavior

This means field permissions are not mere UI hints. They are enforced server-side.

## Config delivery matters to the admin UX

Field permissions also affect what the client receives from the project config.

Important behavior for non-admin users:

- effective readonly information is exposed through `yourPermissions[collection].readonlyFields`
- statically hidden field definitions are removed from `fields[]`
- `hiddenFields` arrays are not delivered as-is to non-admin clients
- eval-based field rules stay relevant because they depend on document context

Implication:

- Nova and other clients should reflect the real config/permission output instead of pretending every field is always present and editable

If later agents debug “missing” fields in the admin, check permission-shaped config delivery before assuming the admin UI is broken.

## Dynamic field rules

Use eval-based field rules when permissions depend on document state.

Typical examples:

- a field becomes readonly after approval
- an internal note is hidden from non-admin roles
- a billing field is editable only before status changes

Use these rules to model real editorial transitions, not to create confusing surprises.

For each eval-based rule, later agents should be able to name:

- one allowed write scenario
- one denied write scenario
- the document state that flips the rule

## Admin UX must reflect permission reality

If a field is hidden or readonly for a role, the Nova configuration and layout should support that reality.

Recommended patterns:

- keep critical restricted fields out of primary editorial flow
- place admin-only or system-managed fields in sidebars or dedicated sections
- avoid forms whose main content becomes unusable when half the fields are hidden by role
- design previews so editors can still identify entries even when some internal fields are hidden

Server permissions are authoritative, but poor admin layout can still create a bad workflow.

## Permission matrix before YAML

Before writing or changing permission sets, write down a small matrix for the real actors.

Typical matrix columns:

- actor or role
- collections they can read
- collections they can write
- fields hidden from them
- fields readonly for them
- machine/token access they need

Typical actors:

- public
- editor
- reviewer or publisher
- admin
- machine token or integration

This avoids permission YAML that is locally correct but globally incoherent.

## Tokens and integrations

Remember that token-based integrations can have their own permission sets.

Use this for:

- inbound integrations
- service accounts
- controlled automation
- frontend-to-backend machine use cases when appropriate

Do not reuse broad admin permissions for integrations if a narrow token permission set is enough.

## Permission-driven architecture decisions

Permissions can change the correct data model.

Examples:

- if sensitive internal notes should never be visible to normal editors, consider whether they belong in the same collection or a separate one
- if a public form creates internal records, the public action and the internal collection should have separate permission boundaries
- if a workflow has approval stages, model status transitions and readonly behavior explicitly

## Recommended patterns

### Editorial content workflow

Recommended shape:

- editors can create and update content fields
- publication/system fields may be restricted or conditionally readonly
- admin-only technical fields are hidden or isolated in the UI

### Sensitive internal data

Recommended shape:

- hide internal-only fields from normal editors
- prefer explicit server-side rules over relying on UI omission
- ensure previews do not depend on hidden-only data

### Approval-style workflow

Recommended shape:

- status field controls editability of specific fields
- post-approval fields become readonly via eval rules
- admin or reviewer roles retain the intended override path

## Anti-patterns

- Treating permissions as frontend-only display logic
- Leaving sensitive fields visible and merely asking editors not to touch them
- Using one broad admin token for every integration
- Designing forms that depend on fields many roles cannot access
- Adding dynamic readonly/hidden logic without explaining the editorial workflow it represents

## Verification checklist

After changing permissions or editor workflows, verify all of these:

1. Collection methods match the intended role model.
2. Hidden and readonly field behavior is correct on API reads/writes.
3. Dynamic eval rules behave correctly for the intended document states.
4. At least one representative allowed write and one denied write were checked for each important workflow state.
5. Non-admin config delivery still makes sense for the admin UI and field layout.
6. Nova forms remain usable for the non-admin roles that actually work there.
7. Token/integration permissions are narrower than admin access when possible.
8. `yarn validate` stays clean.

## What an LLM should inspect first

When asked to design permissions on this starter, inspect in this order:

1. the relevant collection YAML
2. the intended human roles and machine integrations
3. field-level readonly/hidden needs
4. whether the current Nova layout still makes sense under those restrictions
5. any workflow states that require dynamic eval rules

This prevents access rules that are technically correct but operationally unusable.