# Overview.Admin

## What it does for you

Publishing Studio adds a review-first release workflow for Capell Pages: work in an isolated workspace, assign a reviewer, approve the change, schedule or publish it atomically, inspect activity history, and recover a previous release. Capell Pages are the supported launch scope. Custom draftable models use an extension contract and are not part of the supported launch scope.

The package keeps coordinated Page changes away from the live site until they have passed review and are published as one versioned release. Editors work in a release workspace, reviewers compare and approve the staged changes, and release managers can publish immediately or schedule the approved workspace. Approval, activity, preview, scheduler, version, and revision history remain available for later investigation.

## Where to work

- **Publishing Workflow** is the command centre for open drafts, review work, schedules, publishing risks, history, and recovery queues.
- **Publishing Studio** lists active workspaces under **Open**, **In review**, **Approved**, and **Scheduled** tabs. Workspace actions include compare, validate, submit, approve, request changes, reject, schedule, preview, and publish when the current state and permissions allow them.
- **Content Scheduler** shows page visibility dates and durable workspace events. Use its **Failed**, **Stuck**, and **Blocked** quick filters when a timed action has not completed.
- **Preview Links** shows the workspace, issuer, expiry, status, and open count for links already issued from a workspace.
- **Stale Drafts** lists Open or In review workspaces untouched for at least 14 days by default. You can change the threshold, request review in bulk, or discard eligible drafts.
- **Activity Trail** and Capell Admin **Page History** provide audit and page-level comparison context when the relevant permissions are assigned.

## Set up access and background work

The normal package installation publishes and runs the migrations, then creates three additive roles:

- `workspace_editor` can submit work and open the Publishing Workflow and Stale Drafts pages.
- `workspace_reviewer` also receives `approve_workspace`, which covers approval, rejection, and change requests.
- `workspace_release_manager` also receives publish, rollback, release-window bypass, and Content Scheduler permissions.

These roles do not grant the Shield **Workspace** view, create, update, or delete permissions. Grant the required resource permissions as well; assigning a workflow role by itself is not enough to open or edit the workspace list. `View:ActivityTrailPage` is also separate from the default roles.

For site-restricted administrators, a workspace containing pages is visible only when every page in it belongs to one of their assigned sites. Workspaces with no page rows are not site-scoped, so their visibility depends on the Workspace and workflow permissions.

Publish checks, release windows, scheduler retry limits, pruning, and the preview home route are application configuration under `capell.publishing-studio`; the package Settings screen only controls the optional user-resource bridge. Release windows and automatic pruning are disabled by default. If you use any timed publish, unpublish, or reminder, keep both the Laravel scheduler and a queue worker running: the every-minute scheduler dispatches a queued job rather than publishing inline.

## Run a release through review

1. Create a release workspace and make the related edits while it is **Open**. Live rows are not replaced at this stage.
2. Set **Approvals required** in the workspace's collapsed **Workflow** section if the default of two levels is unsuitable. The supported range is 1-10.
3. Use **Compare** and **Validate** before submitting. Submission moves the workspace to **In review**, where content is no longer editable through the normal workspace policy.
4. Each **Approve** records the next level. **Request changes** or **Reject** requires a note and returns the workspace to **Open**. Approval history is retained across resubmission; earlier approved levels are not cleared, and the same account is not prevented from approving successive levels. Use role assignment and operating procedure if distinct reviewers or a fresh approval chain are required.
5. Publish only after the workspace reaches **Approved**, or schedule it for a future time. Release-workspace readiness reports an empty release, missing approval, an active embargo, a closed release window without bypass permission, URL collisions, stale conflicts, and non-clean error-level checks. The final publish path independently enforces every item in that list except an empty approved workspace, so do not bypass an empty-release readiness result. Accessibility, missing-alt-text, and default SEO findings are warnings; broken internal links are errors unless application configuration changes the check set.

Publishing changes, version creation, and the live-version switch run in one database transaction. A failure before commit leaves the previous live data in place. Successful publishing invalidates the affected frontend cache after the transaction.

## Schedule and recover timed work

- A publish time must be in the future and the workspace must already be Approved or Scheduled. An unpublish time must be later than the publish or published time; an embargo cannot end after the planned publish; and a review reminder must be before publish while the workspace is In review, Approved, or Scheduled.
- The scheduler processes up to 50 due events per run. With the default configuration, ordinary failures are retried up to five total attempts after delays of 1, 5, 15, and 60 minutes. An event left **Executing** is reclaimable after 60 minutes. Large backlogs therefore drain over multiple one-minute runs.
- A closed release window moves the event to the next opening. An active embargo leaves it blocked until a later scheduler run can publish it.
- Scheduled publishes recheck the initiating account at execution. A missing or inactive account, revoked publish access, a missing workspace, or a workspace changed after scheduling produces **Skipped stale** and is not retried automatically. Correct the cause and create a current schedule. Legacy events with no stored actor do not have this reauthorisation check.
- Use **Details** to read the stored failure. **Retry** is available on failed durable events to a user who can publish that workspace and executes immediately. **Recover scheduler** appears when stale Executing events exist; exhausted Failed rows remain available through the Failed filter.
- Automatic unpublish sets `visible_until` on pages from the workspace's published version and invalidates their cache; it does not delete the pages. A release containing a home page cannot be automatically unpublished and will follow the normal failure/retry path.
- Review reminders go only to undecided assigned reviewers. A failed notification is recorded and reported, but the parent reminder event still completes and the delivery is not retried automatically.

Disabling `scheduled_publish_enabled` removes the package's scheduled job. Because the prune schedule is registered after that check, it also prevents the optional automatic prune schedule from being registered.

## Share previews safely

A workspace preview link is a public bearer link: anyone who receives the URL can inspect the unpublished workspace without an admin login until the link or its signed URL expires. The default lifetime is four hours. Preview responses disable public caching, and revocation is checked again on later requests, including navigation using the preview cookie.

Treat the URL as sensitive and revoke it when review ends. The token is encrypted at rest and looked up by a hash, while the admin record retains the issuer, expiry, revocation state, last-access time, and open count. It does not identify anonymous viewers, and the open count is not a count of unique people.

**Extend 24h** changes the stored link expiry without changing the token, but it does not mint a new signed URL. Once the URL's original signature has expired, issue a fresh preview link instead of relying on Extend to revive it.

## Roll back and remove old work

The **Rollback-ready versions** item in Publishing Workflow is a recovery queue, not a standalone version-selection screen. Full-release rollback support is permission-gated and immediate when a host exposes the workspace action: it requires confirmation and a reason, targets the published version immediately preceding that workspace's version, and restores the whole registered manifest atomically. Content introduced after the target version is removed. The action refuses an unpublished, already-live, empty, or incomplete target before changing live data.

The package's current Workspace resource lists active states only, so do not assume published workspaces are available there for one-click full-release rollback. Capell Admin **Page History** currently compares immutable page revisions but does not expose a restore action. Confirm that your host application exposes the required full-release or entity-restore action before relying on Publishing Studio for incident recovery.

Discarding from **Stale Drafts** soft-deletes only Open or In review workspaces and preserves their stored history. The console command `capell:publishing-studio:prune` is a separate destructive cleanup: without IDs it permanently removes Abandoned workspaces and their draft rows, and `--dry-run` reports the targets first. Supplying `--id` bypasses the status filter and can permanently remove a workspace in any state, so resolve and review exact IDs before using it. Automatic pruning is opt-in.

## See the workflow

[Watch the captioned 20-second Publishing Studio workflow proof](https://docs.capell.app/packages/publishing-studio/videos/workflow/publishing-workflow.mp4), then use the detailed workflow guide for the responsibilities and controls at each stage.