# Unified Administration Pages

Status: revised direction A accepted and implemented locally (2026-09-12).
The owner selected the latest collapsible context shelf A after restoration of
the original Core. Core and session management must remain functionally unchanged;
the five Administration pages and global context are the implementation scope.
Prototype history remains in `frontend/prototypes/`, including
`administration-review/README.md` and `context-shelf/README.md`.
Final integration remains on the server.
See [implementation and acceptance evidence](../reports/2026-09-12-context-shelf-a-implementation.md).

## Problem Statement

Workspace and Pi open over the work area while Database, Memory and Evidence have
different page structures. Administrators need five predictable, independently
accessible pages that fit beside the Omics Portal sidebar and below its red header.

## Solution

Use the chosen A / Workbench direction for all five Administration Pages: a warm
page heading, restrained red actions, readable serif titles, sans-serif controls,
compact identity/status information, and an index/detail work area appropriate to
each domain. Keep B / Inspector and C / Operations Deck as recoverable prototypes.
Navigation remains on the right, collapsing within the available application width.

## User Stories

1. As an administrator, I want every management entry to open a full page, so that I can use the entire work area.
2. As an administrator, I want the five pages to share hierarchy and typography, so that actions and current context are predictable.
3. As an administrator, I want to refresh or bookmark a management page, so that I can return directly to it.
4. As an administrator, I want Back and Forward to restore navigation, so that browser controls behave normally.
5. As an administrator, I want unsaved edits protected during navigation, so that leaving a page does not silently discard work.
6. As an administrator, I want existing permissions enforced on direct links, so that a URL cannot bypass access controls.
7. As a reviewer, I want my active session retained while visiting Administration, so that navigation does not restart or stop Pi.
8. As a workspace operator, I want to select a workspace and inspect its source, runtime requirements and validation, so that I know which environment I am preparing.
9. As a workspace operator, I want preprocessing beside that workspace's readiness, so that the operation's target is explicit.
10. As a workspace operator, I want catalog revision and preprocessing diagnostics, so that I can understand missing prerequisites and stale derived data.
11. As a database operator, I want configuration, synchronization, descriptions and sensitivity in Database management, so that ownership of catalog changes remains clear.
12. As a database operator, I want a link to the related workspace's preprocessing status, so that I can complete preparation after catalog changes.
13. As a Memory curator, I want existing filtering, CRUD, links and index recovery inside the shared workbench, so that the redesign preserves my workflows.
14. As an Evidence curator, I want browsing, source review and file-maintenance instructions inside the shared workbench, so that external Markdown editing remains the authoring workflow.
15. As a Pi operator, I want runtime status, catalog defaults, models and diagnostics in a page, so that I can inspect the installation without a management popup.
16. As a portal user, I want layout based on the available container width, so that a desktop viewport with a wide portal sidebar still works.
17. As a keyboard or mobile user, I want accessible navigation and non-overlapping controls, so that all five pages remain usable at narrow widths and zoom.
18. As a product owner, I want B and C preserved, so that an individual page can adopt another design later.

## Implementation Decisions

- Five peer Administration Surfaces, independent of active session existence.
- One collapsible top shelf A selects workspace and canonical interaction model for Core and all Administration pages. No duplicate operational selectors inside those pages or the Core composer.
- Each explicit choice is remembered independently per browser origin, application mount and authenticated principal. Absent an explicit choice, use the installation default. Removed/unavailable choices require explicit correction, never silent substitution.
- Neither Core nor Administration activities are enabled until both choices resolve to available catalog entries. Background refresh errors retain already validated context and mounted drafts.
- Workspace/model changes are locked during Core or Administration operations. Navigation itself does not cancel those operations: visited Administration pages and the original Core stay mounted.
- Resume returns the session's pinned workspace in its lifecycle response and adopts that workspace without replacing the global model. Older responses can fall back to the session manifest.
- Preserve the original eight-phase workflow, left activity log, gate widgets, composer, My sessions/All sessions tabs, groups, archive and session lifecycle. A navigation drawer remains reachable when the log is open or the available width is narrow.
- Shared Workbench page/header/layout primitives; data ownership and mutation APIs remain domain-specific.
- Namespaced `thoth_route=administration/<surface>` query routing, preserving host path, other query parameters, fragment and history state. Optional `thoth_workspace` carries only a stable workspace identity for cross-links.
- Unsaved Administration changes block in-app navigation, browser Back/Forward, and context changes. Save successfully or explicitly cancel inside the editor before leaving; navigation does not offer automatic discard. Reload gets native before-unload protection. Busy state locks context selection, not read-only cross-page navigation.
- Workspace owns readiness and full preprocessing. Database owns binding, physical schema synchronization, descriptions and sensitivity. Database status links to workspace preparation; it does not duplicate the run action.
- Preprocessing permission remains the existing backend permission. This UI uses the already unified Installation Model Catalog (`defaults.interaction`) and does not introduce another model authority.
- A shared responsive frame uses available container width, scoped CSS and bounded scrolling. The portal remains the owner of its header and left sidebar; Thoth does not duplicate them. The host can set `--thoth-app-height` to its available height below the header.
- Existing catalog grids remain appropriate for tabular data; form content is inline in the work area. Short confirmations and secondary operation/history panels may remain dialogs/panels.
- English interface labels; persisted document content retains the workspace language.
- A is the production direction. The three read-only prototypes and their launch script remain available and are not imported by production code.

## Testing Decisions

- Verify public behavior at the existing AppShell and management-page boundaries with MSW API fixtures; avoid tests of private state or CSS implementation details.
- Cover all five direct routes, browser history, host URL preservation, permission denial, guarded navigation and retained session behavior.
- Exercise workspace-specific preprocessing targeting and database-to-workspace navigation with authoritative API status fixtures.
- Use the existing authenticated Playwright stack to verify full pages, forms, container resize, narrow screens and a simulated portal header/sidebar. Fixtures avoid mutating the installed PSD knowledge.
- Run frontend typecheck/build, focused tests while implementing, and the full frontend test suite at integration.

## Out of Scope

Schema migrations, a new preprocessing service, Evidence web editing, new model configuration authority, actual deployment into Omics Portal, production deployment, and deletion of prototype variants. The only additional backend contract change in this UI increment is the pinned workspace identity in successful Resume responses.

## Further Notes

This implements the page direction recorded by ADR 0020, refined by the owner's
2026-09-12 acceptance of shelf A and explicit functional-preservation requirements.
Testing reuses the existing public UI seams. Ticket breakdown is recorded alongside
this spec as four independently reviewable increments. Gitea publication is pending
authenticated access; no remote issue identifiers are claimed by these local files.