[mmabrouk]

Context

We will rebuild about ten developer views from the old app (/w) in /m, one at a time. Each view must merge hidden, then move to preview, then to on, so that every PR is safe to merge. This PR adds that switch. It ships no view, so users see no change.

Changes

Registry. One file lists every view: web/mobile/src/features/developer/developerViews.ts. The list is empty.

export interface DeveloperView {
    id: string // lowercase kebab-case, for example "testsets"
    label: string // the rail link and the Preferences switch show it
    description: string // one sentence under the Preferences switch
    routes?: readonly [string, ...string[]] // project-relative Next patterns; routes[0] is the nav link
    nav?: {icon: Icon; section: "developer"}
    stage: "hidden" | "preview" | "on"
}

A view with no routes is a gate for part of a shared screen (for example a filter by app on traces and sessions). It has no nav link, and the screen only asks the helper below. The registry imports no view code.

Stages.

Stage	Nav link and route page	Preferences switch
hidden	no; the route page shows "not found"	no
preview	only for a user who turned it on	yes, under Feature Flags
on	yes	no

Deployment override. Set AGENTA_DEVELOPER_VIEWS=testsets,endpoints on the web container. web/entrypoint.sh writes it to __env.js as NEXT_PUBLIC_AGENTA_DEVELOPER_VIEWS, so a change needs a restart, not a rebuild. A listed view is on for everyone on that deployment, whatever its stage. Note: the brief pointed at NEXT_PUBLIC_SETTINGS_NESTED_NAV as the model, but that flag is not in entrypoint.sh and is build-time only. This one follows the runtime pattern of AGENTA_WALLETS_ENABLED.

Helpers (features/developer/developerViewAccess.ts):

• useDeveloperViewEnabled(viewId): true, false, or null until the signed-in user is known. The first render is always null, so it never differs from the prerendered HTML. It reads only atoms and the list, so a shared screen can call it.
• useEnabledDeveloperViews(): the views the nav shows.
• isDeveloperViewEnabled(view, {previewOptedIn, forcedIds}): the pure rule.
• developerViewPreviewSwitchesAtom: the Preferences switches. The preview choice is a userScopedFlagAtom per view, stored as agenta:settings:<user id>:developer-view:<view id>.
• <DeveloperViewGate viewId="..."> (features/developer/DeveloperViewGate.tsx): wraps a view's route page. It renders the view, the app's "not found" page, or nothing while the user is unknown.

Nav. useMobileNavItems adds a "Developer" section after Sessions with one link per enabled view that has a route and a nav entry. With no enabled view, it adds nothing. The links use prefetch={false}. To do this, SidebarConfig gets an optional prefetch field, and NavMenu passes it to its three nav <Link>s. Unset keeps the Next default, so /w does not change.

Preferences. PreferencesPage (@agenta/settings-ui) takes optional hostItems: rows that only one app shows, added after the shared rows of a section. /m passes one Feature Flags row per view in preview. /w passes none. The shared structure test (preferencesTab.render.test.tsx) is unchanged and passes.

Not-found page. The body of pages/404.tsx moved to components/PageNotFound.tsx, so the gate shows the same page.

How a view PR uses this

1. Add the entry with stage: "hidden".
2. Add the route page under src/pages/w/[workspace_id]/p/[project_id]/ and wrap the screen in <DeveloperViewGate viewId="...">. Do not import the view anywhere else.
3. For a gate on a shared screen, leave out routes and nav, and show the part only when useDeveloperViewEnabled(id) is true.
4. Change stage in its own small PR.

Left for the flip milestone: sending /w pages to /m

/w sends a page to /m through mobileRouteFor in @agenta/shared/utils/mobileGate. The /w middleware and useClassicModeRedirect both call it. The /w middleware cannot read the /m registry or the /m runtime env. So the PR that moves a view to on also adds its paths to mobileRouteFor (and the inverse to desktopRouteFor), with a test in @agenta/shared. That is a few lines in the shared package and touches no /w file. No view is on yet, so this PR does not change it. A view in preview, or one forced on by the env, does not redirect from /w. The design note docs/design/m-developer-views/registry.md has the full contract.

Tests

• New: developerViewAccess.test.ts (each stage, the preference switch per user, the env override, a gate with no route), developerViews.render.test.tsx (the nav section renders links with prefetch=false, adds nothing without enabled views or for a gate; the route gate for each stage, an unknown id, and an unknown user), preferencesTabDeveloperViews.render.test.tsx (preview views appear under Feature Flags, and the switch turns the view on).
• pnpm --filter @agenta/mobile types:check, lint (0 errors), pass. The full pnpm --filter @agenta/mobile test passes except one test: agentPermissions.render.test.tsx > "keeps permission editors out of the real Advanced drawer". It fails the same way on release/v0.128.2 without this change, so it is not caused here. lint also passes for @agenta/navigation, @agenta/navigation-ui and @agenta/settings-ui.
• Not checked in a running app: nothing is visible until a view is registered.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Agenta-AI/agenta
• Branch: feat/m-views-registry
• File: .coderabbit.yaml
• Commit: f70ab50
• Layers: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 25fefaa3-46ea-419d-b622-b96050c0d71c

Commits

Reviewing files that changed from the base of the PR and between 426c0e9 and f70ab50.

Files selected for processing: 19

• docs/design/m-developer-views/registry.md
• web/entrypoint.sh
• web/mobile/src/components/PageNotFound.tsx
• web/mobile/src/features/developer/DeveloperViewGate.tsx
• web/mobile/src/features/developer/developerNavItems.ts
• web/mobile/src/features/developer/developerViewAccess.ts
• web/mobile/src/features/developer/developerViews.ts
• web/mobile/src/features/nav/useMobileNavItems.tsx
• web/mobile/src/features/settings/PreferencesTab.tsx
• web/mobile/src/lib/env.ts
• web/mobile/src/pages/404.tsx
• web/mobile/tests/unit/developerViewAccess.test.ts
• web/mobile/tests/unit/developerViewFixtures.ts
• web/mobile/tests/unit/developerViews.render.test.tsx
• web/mobile/tests/unit/preferencesTabDeveloperViews.render.test.tsx
• web/packages/agenta-navigation-ui/src/NavMenu.tsx
• web/packages/agenta-navigation/src/types.ts
• web/packages/agenta-settings-ui/src/PreferencesPage.tsx
• web/packages/agenta-settings-ui/src/index.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 2 remain after this review.

Summary

Summary by CodeRabbit

• New Features

  • Added support for staged developer views, with preview access controlled per user and selected views available through deployment configuration.
  • Enabled available developer views to appear in mobile navigation.
  • Added preview switches to Preferences, where users can opt in to eligible views.
  • Improved not-found pages with a consistent back-navigation experience.

• Documentation

  • Documented developer-view stages, access rules, navigation, and route requirements.

• Tests

  • Added coverage for view access, navigation, and preview switches.

The mobile app now has a staged developer-view registry, per-user preview access, deployment overrides, navigation links, and route gating. Preferences can display host-provided preview switches. The changes also add runtime configuration support, a shared not-found component, tests, and registry documentation.

Changes: Mobile developer-view rollout

Layer / File(s)	Summary
Registry and access state docs/design/m-developer-views/registry.md, web/entrypoint.sh, web/mobile/src/features/developer/developerViews.ts, web/mobile/src/features/developer/developerViewAccess.ts, web/mobile/src/lib/env.ts, web/mobile/tests/unit/developerViewFixtures.ts, web/mobile/tests/unit/developerViewAccess.test.ts	Defines view stages and navigation metadata, parses deployment-forced view IDs, and applies stage and per-user preview access rules. Runtime configuration exposes the deployment setting. Tests cover stage access, forced IDs, and user-specific preferences.
Mobile navigation and route access web/packages/agenta-navigation/src/types.ts, web/packages/agenta-navigation-ui/src/NavMenu.tsx, web/mobile/src/components/PageNotFound.tsx, web/mobile/src/features/developer/DeveloperViewGate.tsx, web/mobile/src/features/developer/developerNavItems.ts, web/mobile/src/features/nav/useMobileNavItems.tsx, web/mobile/src/pages/404.tsx, web/mobile/tests/unit/developerViews.render.test.tsx	Adds optional link prefetch configuration and uses it for developer navigation links. The route gate renders nothing while access is unknown, renders children when enabled, and otherwise renders the not-found component. Tests cover navigation and gate states.
Preview controls in Preferences web/packages/agenta-settings-ui/src/PreferencesPage.tsx, web/packages/agenta-settings-ui/src/index.ts, web/mobile/src/features/settings/PreferencesTab.tsx, web/mobile/tests/unit/preferencesTabDeveloperViews.render.test.tsx	Adds host-provided preference rows and exports their type. The mobile Preferences tab maps preview views to Feature Flags switches. Tests cover switch display and opt-in behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  actor User
  participant PreferencesTab
  participant developerViewPreviewSwitchesAtom
  participant developerViewPreviewAtomFamily
  participant enabledDeveloperViewsAtom
  participant useMobileNavItems
  User->>PreferencesTab: Toggle a preview switch
  PreferencesTab->>developerViewPreviewSwitchesAtom: Set opted-in state for the view
  developerViewPreviewSwitchesAtom->>developerViewPreviewAtomFamily: Update the user's view preference
  developerViewPreviewAtomFamily-->>enabledDeveloperViewsAtom: Supply preview preference
  enabledDeveloperViewsAtom-->>useMobileNavItems: Return enabled views

Loading

Merge Risk: Minimal · up to f70ab

No developer views ship in this change, and no concrete issue remains that should block merging after normal checks.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly identifies the main change: adding staged developer-view access in the frontend for /m.
Description check		The description accurately covers the registry, rollout stages, access controls, navigation, Preferences integration, tests, and deferred /w routing changes.
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 18 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[github-actions]

📘 Docs preview

Status	✅ Ready
Preview	https://pr-7985-agenta-docs-preview.mahmoud-637.workers.dev/docs/
Inspect	Actions run
Commit	f70ab50e5a3b087fed5fa05eb47d4769ca2c8954

This comment updates in place on every push.

[github-actions]

Website preview

Preview URL: https://pr-7985-agenta-website-preview.mahmoud-637.workers.dev

Built from f70ab50e5a3b087fed5fa05eb47d4769ca2c8954. This comment updates in place on every push.

[github-actions]

Railway Preview Environment

Item	Value
Status	stopped
Commit	f70ab50e5a3b087fed5fa05eb47d4769ca2c8954
Manual expiry (UTC)	Not granted
CI deadline (UTC)	Not granted
Workflow	https://github.com/Agenta-AI/agenta/actions/runs/41486780693

Preview use finished or expired. Environment absence verified; retained storage requires separate provider accounting.

Post /preview as a new comment to request a one-hour preview. Repeating it while active does not extend the hour.
Preview data is disposable. Expiry is enforced by the next successful cleanup sweep, not an exact timer.
Environment deletion stops its compute. Provider-retained storage and permanent services may still be billed.

[mmabrouk]

🤖 The AI agent says:

Review loop result, 2 rounds, base 395a543facaa. Round 1 reviewed b192a1a5c1ab, round 2 reviewed 1d4c219f5865. The head after the last commit (f70ab50e5a3b) only deletes one comment.

Lens	Final rating
Slop	Low
Simplify	Low
Correctness (Codex)	Low
Naming	Low

Fixed: a stale comment in PreferencesPage (it said hosts add no rows, but hostItems does); the "never prefetch" wording in a code comment, a test name and registry.md; enabled renamed optedIn on the preview switch atom and setter; the registry.md heading "Forced views"; a new "Names" section in registry.md; one comment that repeated the hook docs.
Left on purpose:

• Hover prefetch (Codex slop, Medium in round 1). prefetch={false} stops prefetch on scroll into view. Next still prefetches when the user hovers the link, which means the user is about to open that view. Nothing loads on shared pages without that choice. registry.md now says so.
• "Developer" in the rail next to the "Developer Mode" switch (Opus naming, Medium in round 1). Developer Mode will show these /m views, so both words name the same thing. Recorded in registry.md.
• A union type for HostPreferenceItem.section. PreferenceSection.key is a plain string, so it needs a wider change.
• A needsPreviewSwitch helper for the forced-id rule (Low, optional).

Contract: unchanged (entry shape, useDeveloperViewEnabled, useEnabledDeveloperViews, DeveloperViewGate, AGENTA_DEVELOPER_VIEWS). Only the internal preview switch field was renamed.

Checks run: the three developer view test files (17 tests pass), eslint on the changed files, @agenta/mobile types:check (no output). Speed rule: developerViews.ts imports only a type from phosphor and no view code; the nav adds only prefetch={false} links and nothing from a view into shared pages.

Base branch test: agentPermissions.render.test.tsx ("keeps permission editors out of the real Advanced drawer") fails the same way on a read-only checkout of the release branch (commit 98a64c9cd4, no web/mobile source changes between it and the current branch tip). It is not caused by this PR and is not fixed here.