---
owner: gmikcon
status: active
last_reviewed: 2026-11-19
review_interval: 30d
confidence: high
source_of_truth: owner-confirmed
---

# Gnexus Book UI

The Gnexus Book UI is a custom Vue.js application based on `gnexus-ui-kit`.

`gnexus-ui-kit` is the official UI kit and design-system layer for Gnexus projects. It is consumed as a dependency so the shared visual style can be managed centrally across projects.

Source UI kit repository:

```text
https://git.gnexus.space/root/gnexus-ui-kit
```

## Current implementation

The UI is a maintenance console, not a document editor. It provides:

- an auth gate backed by gnexus-auth SSO (`/api/me`, explicit sign-in, logout);
- drawer navigation with `GnPageHeader` on every page;
- documentation browsing, search, frontmatter/body view, version history, diff and restore;
- inventory browsing with JSON and generated raw views;
- draft changesets with validation results and apply/publish;
- validation and freshness reports with issue details;
- MCP personal key management (create, rotate, revoke, copy-once token);
- settings with per-service language selection and account details;
- en/uk/ru localization through `src/i18n/`.

All writes go through the backend API; the UI does not edit files directly.

## Architectural notes

- `src/main.js` is the single-page application: no router, page switching is local state.
- Navigation labels are `computed` because `t()` reads a reactive locale; module-level
  arrays would freeze the initial language.
- Toasts require `GnToastProvider` at the app root; `useToast()` is used inside it.
- Authentication is disabled when the server has no gnexus-auth client configured;
  the UI then runs open for local development and hides the MCP keys page.
- The login button redirects to `/api/auth/login`. gnexus-auth redirects back to
  `/auth/callback`, so the dev server proxies `/auth` and `/webhooks` as well as `/api`.

## Local dependency

```json
"gnexus-ui-kit": "file:../../gnexus-ui-kit"
```

This keeps the UI kit as a package dependency while allowing local updates to the official kit source.

Avoid copying UI kit styles into this project unless there is a temporary integration reason. Prefer upstream changes in `gnexus-ui-kit` for shared style decisions.

## Development

```bash
cd ui
npm install
npm run dev
```

The dev server runs on port `3006` and proxies `/api/*`, `/auth/*`, and
`/webhooks/*` to the FastAPI backend on `127.0.0.1:3005`. Build with `npm run build`;
the output is `dist/`.
