Navigating the UI

Trinity's interface is built around a sidebar on the left with contextual pages for each major feature area. This page is a tour of what's where.

The sidebar has a fixed header (Trinity logo + user menu, scope switcher, project selector) and two collapsible sections underneath:

  • Project — items tied to the active project, shown only when a project is selected. Items unlock progressively as the project advances through its phases (onboarding → imported → structured → planning → executing).
  • Hub — workspace-wide items, always available.

Open one section at a time by clicking its header. A task indicator and the Trinity version label sit at the bottom of the sidebar.

Scope switcher

Directly above the project selector, the scope switcher lets you flip between your Personal workspace and any Team you belong to. Projects, settings, and data plane are all scoped to the active scope.

Project selector

Shows the active project name. Click to switch projects or open the New Project / Import Existing flow. Projects from the current scope only.

Project section

Items in order of appearance (some only unlock later):

  • Roadmap — onboarding roadmap; visible during the onboarding phase only
  • Dashboard — release-scoped planning view with PRD tabs, phase progress, and stats
  • Code — read-only code browser for your project's repos (file tree, branch switcher, Cmd+P file search)
  • Stories — browse and filter stories for the active release
  • Run — execution control, active stories, gate approvals
  • Releases — create releases, wire dependencies, track lifecycle state
  • Architect — add features or edit stories through a conversational interface
  • Align — project health check (roadmap review pre-PRD, drift detection post-PRD)
  • Audit — on-demand codebase quality scanner
  • Settings — per-project configuration (details, repos, collaborators, codebase map, targets, secrets, danger zone)

Hub section

Always visible, regardless of project state:

  • Activity — global activity feed with filters (project, category, actor)
  • Recaps — activity summaries and PDF report export
  • Metrics — execution analytics and AI cost tracking
  • Knowledge — project knowledge base (vault): architecture, learnings, audit reports
  • Gotchas — curated pitfalls library by language, framework, and tool
  • Teams — team management and invitations
  • Requests — pending invites (team, sponsorship, storage), plus project move approvals. The badge aggregates actionable items across every team you belong to (no need to switch scopes); the team switcher also shows a dot next to each team that has pending actions.
  • Team Settings — team-wide defaults (team scope only; visible to owners and managers)
  • Settings — app-wide configuration

Task indicator

The sidebar shows a task indicator when background operations are running — PRD generation, align, audit, onboarding generation, etc. It displays the current phase and progress.

Key Page Layouts

Planning Dashboard

Your command center for the active release's plan:

  • PRD tabs at the top — switch between PRDs belonging to the current release
  • Phase progress — visual progress bars for each phase
  • Stats cards — story counts, completion rates, dependency status
  • Generate PRD button — create a new plan iteration

Release selection happens at the Hub/project level, not here — see the Releases page.

Story Graph

The dependency graph visualizes relationships between stories in the active release:

  • Nodes represent stories, colored by status (pending, running, complete, failed)
  • Edges show dependencies
  • Zoom and pan to navigate large graphs
  • Click a node to open the story detail panel
  • Save layouts to preserve custom arrangements

Run Page

Shows execution state for the active release:

  • Coordinator status — one coordinator per (project, release) pair; running, draining, or idle
  • Active stories — currently executing with pipeline phase indicators
  • Gate queue — stories paused at gates awaiting your input
  • Worker status — how many workers are active and what they're doing

Releases Page

Releases are organized into columns by lifecycle state:

  • Not Started — status created; no stories have started yet
  • In Progress — status in_progress; at least one story has merged into the release branch, more work still pending
  • Ready to Release — every story terminal, awaiting manual transition to staging or release
  • Releasing — release pipeline running (preflight, SEO, release notes, tagging)
  • Released — completed releases (historical record)

Click any release card to open its detail panel:

  • Release Dashboard — four tactical tiles (Run Project, Run SEO, Run Audit, Generate Notes) sit at the top. They run their respective standalone agents against the current release worktree without advancing the lifecycle. While the release is in any staged-family status (staged, staging_failed, partially_staged), every tile except Run Project shows a Locked badge.
  • Commit row — primary lifecycle buttons (Push to Staging, Release, Retry Failed Repos, Yank Back, Stop). What's visible depends on the current status.
  • Staging Drift + CI on Staging tiles — appear during staged-family statuses. The drift tile surfaces a Redeploy to Staging button when drift is detected.
  • Per-Repo Status — table of each repo with its current staged tip, drift state, and CI status.
  • PRDs list — every PRD assigned to the release. Each row has a Move action (reassign to another unshipped release) and a Reparent action (set a different release as parent without moving the PRD); both are available only while the release is created or in_progress.
  • Dependency Editor — manage release dependencies.
  • Automation overrides — per-release autoReleaseToBase / deleteReleaseBranch.

The release pipeline is always triggered manually — you start it either from the release detail panel here, or from the "Ready to release" card on the Run page once all stories are terminal.

Audit Page

Run on-demand codebase quality scans:

  • Run audit — trigger a comprehensive scan of your codebase
  • Chat interface — ask follow-up questions or focus on specific areas
  • Checklist tracking — audit findings are tracked as checklists that auto-update when stories address them
  • History — browse previous audit reports
  • Implement — send findings to Architect to generate fix stories

Story Detail

Click any story (from the list, graph, or run page) to see:

  • Description and acceptance criteria
  • Metadata — difficulty, surface area, dependencies, tags, targets, display ID (prd:phase.epic.story)
  • Pipeline status — which agent phase it's in
  • Agent handoffs — reports from each agent in the pipeline
  • PR and merge status — for completed stories
  • Comments + activity timeline — who changed what, when

Knowledge Base

Organized hierarchically:

  • Books — top-level containers (your project knowledge, gotchas, this user guide)
  • Sections — grouped chapters within a book
  • Chapters — topic areas
  • Pages — individual knowledge articles

Navigate by expanding sections in the left panel, or use the search bar to find specific content across all books.

Help Assistant

A floating help button appears in the bottom-right of every page. Click it to open a chat where you can ask questions about how to use Trinity. The assistant answers from the user guide — it won't make changes to your project. You can paste screenshots to ask about specific UI elements.

Common Actions

Creating a Release

Releases are usually auto-created (the first one gets minted when you generate your first PRD), but you can also create them manually:

  1. Navigate to Releases
  2. Click Create Release
  3. Enter a name, version, and optional description
  4. Link one or more PRDs (or leave empty and move PRDs in later)
  5. Go to Run to start execution for the release

Adding a Feature

  1. Navigate to Architect
  2. Describe what you want in the chat
  3. Architect proposes either adding the PRD to an existing unshipped release or creating a new one — approve or override
  4. Review the generated stories
  5. Confirm to add them to the release

Approving a Gate

  1. Navigate to Run
  2. Look for stories with a gate indicator
  3. Click the gate to review the agent's request (deviation, missing secret, missing assets, etc.)
  4. Choose Approve, Skip, or provide Feedback (re-runs the feedback pipeline)

Searching the Knowledge Base

  1. Navigate to Knowledge
  2. Use the search bar at the top
  3. Results show matching pages across all books
  4. Click a result to jump directly to that page

Running a Codebase Audit

  1. Navigate to Audit
  2. Click Run Audit to start a scan
  3. Optionally type a focus area in the chat
  4. Review findings — each has a severity, category, and recommendation
  5. Click Implement to send findings to Architect for story generation

Exporting a Report

  1. Navigate to Recaps
  2. Click the Export Report button
  3. Choose report type (Executive or Technical)
  4. Select the time period
  5. Click Download to get a PDF

Setting Up a Project on This Device

Trinity owns its own clone of every project at ~/.trinity/projects/ — you don't pick a folder. You'll hit this flow in two situations:

  • Switching devices — projects you created on another machine show up in the project list but aren't yet cloned here. Click Set up on the project row to clone the workspace into Trinity's managed location.
  • Repairing a broken workspace — if you (or something else) deletes the workspace folder or one of its repos, a yellow Workspace incomplete banner appears at the top of every project page, listing the missing repos. Click Repair workspace and Trinity re-clones only the missing pieces, leaving valid clones alone.

In both cases there's nothing to configure — Trinity handles the clone location, materializes any project secrets and service-config files, and refreshes workspace-doc assets so the trunk is whole when it returns.

  • Sidebar switches between major sections
  • Browser back/forward works for navigation history
  • Knowledge Base has its own search bar
  • URLs are deep-linkable: stories (/stories/{id}), knowledge pages (/knowledge/{book}/{section}/{chapter}/{page}), gotchas (/gotchas/{book}/{section}/{chapter}/{page}). Releases are selected from a side panel within /releases rather than addressed by URL.

Responsive Design

Trinity is designed primarily for desktop use. The interface works best on screens 1280px or wider. On smaller screens (below 1024px) the sidebar collapses into a drawer with a sticky header at the top.