--- Status: Approved Owner Role: Requirements Intake Created: 2026-05-11 Approved: 2026-05-11 Depends On: requirements-000001-auth-admin-bootstrap Validation: bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh; ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md || true; ai/commands/workflow-summary.sh || true --- # UI Foundation Admin Experience Requirements ## Raw Idea We want to improve the app UI and admin experience. The current auth/admin functionality works as a base, but the UI needs a more polished and organized design system. We want: - a new bright default theme inspired by Laravel/WorkOS-style clean admin/auth interfaces. - a dark theme inspired by Railway-style dark UI. - the current existing theme retained as an alternative. Themes should be modular and switchable so additional themes can be added later. We also want a practical base UI component foundation: - cards - forms - CTAs - buttons - inputs - tables/lists - dropdowns - tabs - alerts - badges - empty states - loading states - dialogs - app shell/navigation primitives Goal: Create a simple, extensible, mobile-first UI foundation. Do not attempt to replicate full PrimeNG or Angular Material feature parity. Admin user management should support: - first name - last name - role - password/setup credential behavior - avatar Admin UX should include: - dropdown menu - Users section - improved list/create/edit workflows - clearer visual organization - mobile usability - less awkward layout/interaction than the current version We also want a future "Dev Console" admin section. The long-term idea is to show tmux/Codex session visibility and eventually allow controlled interaction. Arbitrary command execution exposed through a web UI is a major security risk. Requirements Intake must explicitly separate: - Phase 1: - local/dev-only visibility - read-only stream - safe status visibility - possibly restricted interaction - Phase 2/Future Scope: - command execution/input - only after dedicated security review - explicit dev-only gating - strong environment protections - admin-only access - auditing/logging - no production exposure - secrets protection/redaction Design references to consider conceptually: - WorkOS/AuthKit-style auth/admin UX. - Laravel Nova/Filament admin organization. - Railway-style dark theme direction. - PrimeNG and Angular Material as reference inventories only. Do not assume adopting Angular Material or replacing PrimeNG unless future planning explicitly approves it. Suggested placeholder theme names: - Lumen (bright) - Railnight (dark) - Classic (current existing theme) ## User Perspective - Administrator: needs a clearer, more polished admin area to navigate user-management workflows, understand system state, and complete create/edit tasks efficiently on mobile and desktop. - Standard user: needs the authenticated app shell to remain responsive, readable, and free of admin-only controls they cannot use. - Developer/operator: needs privileged local/dev tooling to see and interact with tmux/Codex sessions through trusted admin/operator access, including LAN/VPN/Tailscale development usage, without production exposure. - Remote Dev Operator: needs to leave a trusted dev machine running at home, reach the app from a phone or iPad over LAN/VPN/Tailscale, inspect requirements/chunks/work packages, approve workflow steps, send prompts/instructions, and keep Codex/tmux work moving while away. - Future designer/developer: needs theme and component foundations that are modular enough to extend without rewriting the app shell or replacing the whole UI stack. - QA/human reviewer: needs observable UI paths, theme switching, admin workflows, and safety boundaries that can be validated without hidden local knowledge. ## User Workflows - Theme selection: - User opens the app with the default bright theme. - User can switch between Lumen, Railnight, and Classic where the theme switcher is exposed. - The selected theme persists according to the chosen persistence rule. - The app remains readable and responsive after switching themes. - Admin navigation: - Admin signs in. - Admin sees admin-only navigation, including a Users section and, if in scope for the selected phase, a Dev Console entry. - Standard users do not see admin-only navigation. - Mobile users can reach the same admin workflows through stacked or responsive navigation without losing the existing mobile-first behavior. - Admin user management: - Admin views users in a clearer list or table layout. - Admin creates a user with required identity fields and setup credential behavior. - Admin edits supported user fields such as first name, last name, role, and avatar information. - Admin receives clear validation, loading, empty, success, and error states. - Dev Console Phase 1: - Admin or Remote Dev Operator in an explicitly enabled local/dev environment opens the Remote Dev Operator Console from desktop, phone, or iPad. - The operator views active requirements, chunks, work packages, workflow summaries, canonical state, and recent reports. - The console may show tmux/Codex session output, workflow summaries, chunk state, session status, and logs directly. - The console may support terminal/session interaction, command input, prompt submission, and safe workflow transition actions in trusted local/dev mode. - The operator may continue work over LAN/VPN/Tailscale while the primary dev machine remains running at home. - The UI is clearly labeled as privileged local/dev tooling and must not be exposed in production. - Telegram remote control: - Telegram remains a parallel/fallback remote-control path. - Future Telegram and Web Console work should share the same workflow commands/helpers where practical instead of creating separate workflow interpretations. - Dev Console Phase 2/Future: - Broader exposure, production use, or public/internet-exposed command control requires dedicated security review and explicit approval. ## Functional Requirements - The UI must provide a modular theme system with at least: - `Lumen` bright default theme. - `Railnight` dark theme. - `Classic` existing/current theme. - Theme implementation must be structured so future themes can be added without rewriting app shell or component behavior. - A theme switcher must exist for authenticated users. - Theme preference must persist locally in the browser by default and may later move to backend user preferences. - If no saved preference exists, the app should default to Lumen, with system preference considered only if implementation planning finds it low-risk. - The existing mobile-first stacked-view behavior and responsive app shell behavior must be preserved unless explicitly redesigned later. - The UI foundation must provide a practical initial set of primitives: - app shell/layout. - top navigation/header. - admin dropdown menu. - sidebar or section navigation if needed. - card. - stat/summary card. - button. - icon button. - link button. - form field wrapper. - text input. - password input. - select. - checkbox or switch. - avatar. - badge/status pill. - alert/callout. - empty state. - loading state. - table/list. - modal/dialog. - tabs. - CTA block. - toast or inline feedback. - mobile stacking/responsive container. - The foundation should improve consistency for spacing, typography, form behavior, validation/error states, loading states, empty states, and feedback. - The foundation must not attempt full PrimeNG or Angular Material feature parity. - PrimeNG and Angular Material may be used as reference inventories only unless a later plan explicitly approves dependency or architecture changes. - The first implementation must not assume replacing PrimeNG. - The component strategy must use a mixed approach: - preserve PrimeNG where useful. - add thin local, app-opinionated wrapper/foundation components for repeated app UX patterns. - normalize spacing, typography, labels, validation/error presentation, loading/empty states, CTA styling, theme behavior, and mobile responsiveness. - avoid wrapping highly specialized PrimeNG controls until a repeated app need exists. - Admin user management must support first name, last name, role, password/setup credential behavior, and avatar behavior once those backend/API capabilities exist. - Admin user management must preserve existing auth/admin safety behavior, including admin-only access and last-admin protections from the approved auth/admin requirements. - The admin navigation model must use a responsive combination of top/header navigation, admin dropdown, and section navigation as needed, while preserving mobile-first stacked behavior. - The admin navigation model must include a Users section. - Dev Console Phase 1 should be framed as a Remote Dev Operator Console, even if the visible admin section label remains "Dev Console". - Dev Console Phase 1 is privileged local/dev operator tooling intended for remote development workflows from desktop, phone, or iPad. - Dev Console Phase 1 may include terminal/session visibility, command input, tmux/Codex interaction, prompt submission, workflow summary visibility, chunk state, session status, and logs. - Dev Console Phase 1 must support viewing active requirements, active/backlog/completed chunks, active/completed work packages, canonical workflow state, workflow summaries, recent reports, and validation status where practical. - Dev Console Phase 1 may support approving or triggering safe workflow transitions when those transitions already have explicit workflow commands and the operator is authenticated/admin-authorized in local/dev mode. - Dev Console Phase 1 may support sending prompts or instructions to Codex/tmux in trusted local/dev mode. - Dev Console Phase 1 must require explicit feature flag or environment guard enablement. - Dev Console Phase 1 must require admin authentication. - Dev Console Phase 1 must clearly label privileged local/dev mode in the UI. - Dev Console Phase 1 may be reachable over LAN/VPN/Tailscale during development. - Dev Console Phase 1 must not be exposed in production. - Public internet exposure, production exposure, or non-dev command control remains out of scope until a dedicated security review approves it. ## Non-Functional Requirements - UI must be mobile-first, then scale to tablet and desktop. - Theme colors must meet reasonable contrast/readability expectations for normal text, controls, alerts, badges, and disabled states. - Component primitives must be accessible enough for keyboard navigation, focus visibility, labels, validation messages, and screen-reader-friendly naming where applicable. - UI copy and layout should reduce operator confusion in admin workflows. - Theme and component implementation should be incremental and compatible with the existing Angular/Tailwind/PrimeNG stack unless later planning approves a larger architecture change. - Dev Console UI must prioritize explicit local/dev gating, production exclusion, admin authentication, privileged-mode labeling, and operator clarity. - Dev Console UI must be usable on phone and iPad for common operator workflows, including inspection, approval, prompt submission, and session output review. - The app must not intentionally print configured secrets or `.env` values, but raw terminal/session output may be visible in trusted local/dev Dev Console mode. Operators are responsible for trusted network access and command hygiene in that mode. ## Data / Model Requirements - Admin user management may require user profile fields: - first name. - last name. - avatar metadata or avatar URL/storage reference. - role. - setup credential or setup-token state. - Avatar behavior should start with initials or generated placeholders plus optional URL/display metadata if already available. File upload/storage is out of scope for the first implementation. - Theme preference should start with client-side browser persistence. Backend user preference persistence is a future enhancement. - Dev Console Phase 1 may surface local/dev session metadata, tmux/Codex output, workflow summaries, active chunk state, logs, and command/prompt interaction state. - Dev Console Phase 1 may surface workflow artifact metadata for requirements, chunks, work packages, reports, validation status, and pass history. - Dev Console output is privileged local/dev operator data. Secret redaction is desirable when practical, but the first trusted local/dev implementation may show raw terminal/session output. ## Permissions / Auth Requirements - Admin user-management screens and actions remain admin-only. - Standard users must not see admin-only navigation or access admin-only routes. - Backend/API authorization remains authoritative for user-management actions; frontend visibility alone is insufficient. - Dev Console Phase 1 must be admin-only, local/dev-only, and enabled by explicit feature flag or environment guard. - Dev Console production exposure is blocked. - Dev Console Phase 1 may support command execution, arbitrary input, tmux/Codex control, prompt submission, and interactive shell/session access only in trusted local/dev environments. - Dev Console Phase 1 may support workflow approvals and safe lifecycle transitions only through existing shared workflow helpers or clearly scoped equivalents. - Dev Console Phase 1 may be available over LAN/VPN/Tailscale during development, but public internet exposure is forbidden. - Broader exposure beyond trusted local/dev usage requires dedicated security review. - Future broader exposure must consider stronger auth/session controls, audit logs, command confirmation policies, role separation, network exposure controls, and secret redaction/hygiene. ## UI / UX Requirements - Lumen should be the default bright theme direction: clean, organized, high-readability admin/auth UI inspired conceptually by WorkOS/AuthKit and Laravel admin tools. - Railnight should be the dark theme direction: modern dark UI inspired conceptually by Railway-style interfaces. - Classic should preserve the current visual direction as a compatibility theme, not necessarily pixel-perfect current styling. - Theme names are accepted placeholders for requirements and may be changed during implementation planning only if the names create implementation friction. - Theme switcher should be available to authenticated users in the user/admin dropdown or another persistent app-shell location. - Theme persistence should use browser-local persistence first. - Admin navigation should use a responsive combination of header/dropdown and section navigation appropriate to the existing shell. - Users section should be clearer than the current layout and support mobile-friendly list/create/edit workflows. - Admin user list should handle empty, loading, error, and success states. - Create/edit user flows should use consistent form layout, validation, and feedback. - Avatar behavior should start with initials/generated placeholders and optional URL/display metadata when already available. Upload/storage is future scope. - Existing mobile-first stacked-view behavior must be preserved unless a future Requirements Review explicitly approves redesign. - Dev Console Phase 1 should clearly communicate that it is a privileged Remote Dev Operator Console for local/dev work, not a production admin feature. - Dev Console Phase 1 must support phone and iPad layouts for viewing state, reviewing output, approving workflow steps, and entering short prompts/instructions. - Telegram should be referenced as a related fallback/parallel operator path where useful, but Telegram expansion is not required in the first UI implementation. ## Phased Rollout - Phase 1 candidate scope: - UI theme foundation with Lumen, Railnight, and Classic. - Theme switcher for authenticated users with browser-local persistence. - Initial component primitives for admin/auth workflows. - Admin app shell/navigation cleanup. - Admin user-management UX improvements for fields and backend capabilities that already exist or are approved. - Remote Dev Operator Console as privileged local/dev admin/operator tooling with feature-flag/environment gating, LAN/VPN/Tailscale development support, mobile/iPad operator workflows, visible local/dev labeling, and no production exposure. - Telegram remains a parallel/fallback remote-control path and should continue sharing workflow helpers where practical. - Phase 2/future scope: - Broader Dev Console exposure beyond trusted local/dev usage. - Hardened redaction, auditing, and permission models for any future wider Dev Console audience. - Stronger auth/session controls, command confirmation policies, role separation, network exposure controls, and production-grade secret hygiene before any higher-stage exposure. - Expanded Telegram/Web Console parity for remote workflow operations. - Advanced design-system documentation site. - Advanced RBAC/permissions UI. - Rich avatar upload/storage flows if not included initially. - Broader component framework expansion. ## Out Of Scope - Product implementation code in this requirements intake pass. - Implementation chunks before Requirements Review. - Replacing PrimeNG or adopting Angular Material without explicit future approval. - Full PrimeNG or Angular Material feature parity. - Complete enterprise design system. - Component framework rewrite. - Full frontend architecture rewrite. - Full data-grid feature parity. - Drag/drop. - Rich text editor. - Advanced charts. - Advanced file uploads. - Full design-system documentation site. - Arbitrary command execution from Dev Console outside explicitly enabled trusted local/dev mode. - Production-exposed Dev Console. - Unrestricted shell access. - Remote internet-exposed tmux/Codex control. - Public/internet-exposed Dev Console command input or controlled interaction before dedicated security review. - Production Dev Console command input, shell access, or tmux/Codex control. - Production-safe Web Console or Telegram remote-control expansion without dedicated security review. - Intentional app display of configured secrets, tokens, `.env` values, or raw credentials outside trusted local/dev terminal/session output. ## Assumptions - The app currently uses Angular, Tailwind, and PrimeNG-based workflows. - Existing auth/admin foundations are available and should remain the base for admin access. - Existing mobile-first stacked-view behavior and responsive app-shell behavior are valuable and should be preserved. - The current theme can be retained as Classic without full redesign. - The first pass should prioritize practical UI consistency and admin operability over a comprehensive design-system framework. - Theme preference should start with browser-local persistence. - Theme switching should be available to authenticated users. - The initial theme scope should cover the auth/admin experience and shared authenticated app shell touched by those flows. - The initial icon strategy should use the existing project icon approach or PrimeNG/PrimeIcons if already available; no new icon dependency should be added unless implementation planning justifies it. - User list behavior should include a simple search/filter path if feasible with existing data, but full data-grid behavior is out of scope. - User setup should reuse the existing auth/admin setup credential mechanism where available. - Role editing should enforce the current `admin` and `user` model without visually promising future roles. - Dev Console is high risk but intentionally privileged; Phase 1 is allowed only as explicitly enabled trusted local/dev admin/operator tooling. - Dev Console may be reachable over LAN/VPN/Tailscale for development workflows, but public internet and production exposure are forbidden. - The remote-development target assumes a trusted dev machine remains running and reachable through LAN/VPN/Tailscale while the operator uses a phone or iPad away from the machine. - Telegram is a parallel/fallback remote-control channel, not a replacement for the Web Console. - Practical accessibility checks for keyboard, focus, labels, validation, and contrast are sufficient for the first implementation. - Screenshots or Playwright/browser smoke should be required for the major theme/admin states in implementation chunks. - UI foundation, admin UX, and Dev Console should be planned as one phased work package with separate implementation chunks or milestones. ## Open Questions No blocking open questions remain for Requirements Review. Implementation planning should still inspect the repo before choosing exact component filenames, token structure, icon imports, test selectors, and Dev Console transport mechanics. ## Acceptance Criteria - Requirements preserve the rough idea and design references. - Requirements identify administrator, standard user, developer/operator, Remote Dev Operator, future developer/designer, and QA/human reviewer perspectives. - Requirements preserve existing mobile-first stacked-view and responsive app-shell behavior unless explicitly redesigned later. - Requirements define Lumen, Railnight, and Classic as initial theme directions. - Requirements state that themes must be modular and extensible. - Requirements define authenticated-user theme switching and browser-local persistence as the first implementation default. - Requirements define a practical initial UI component foundation without full PrimeNG or Angular Material parity. - Requirements avoid assuming Angular Material adoption or PrimeNG replacement. - Requirements define the mixed PrimeNG plus thin local wrapper component strategy. - Requirements define admin user-management UX goals for first name, last name, role, password/setup credential behavior, and avatar. - Requirements define first-pass avatar behavior as initials/generated placeholders with optional URL/display metadata, with uploads out of scope. - Requirements define user setup as reusing the existing auth/admin setup credential mechanism where available. - Requirements define admin navigation expectations, including Users and possible Dev Console sections. - Requirements define Dev Console Phase 1 as privileged local/dev admin/operator tooling with command/session interaction allowed only behind explicit environment gating. - Requirements define Remote Dev Operator Console workflows for phone/iPad use over LAN/VPN/Tailscale. - Requirements define viewing workflow artifacts/state, inspecting tmux/Codex output, sending prompts/instructions, and triggering safe workflow transitions as Phase 1 local/dev goals. - Requirements include Telegram as a parallel/fallback remote-control channel that should share workflow helpers where practical. - Requirements forbid production or public internet exposure of Dev Console. - Requirements require future broader Dev Console exposure to receive dedicated security review. - Requirements include accessibility, mobile, operator sanity, theme switching, and visual consistency expectations. - Requirements include backend/API, frontend/browser, and workflow testability expectations. - Requirements identify no remaining blocking open questions for Requirements Review. - Requirements are not approved. - No product code or implementation chunks are created from this intake pass. ## Runtime Smoke Expectations - Requirements-only runtime smoke is not applicable in this intake pass. - Future frontend/browser smoke should cover: - app loads. - authenticated shell renders. - existing mobile-first stacked behavior remains usable. - theme switcher changes between Lumen, Railnight, and Classic. - selected persistence behavior works after refresh or re-login, depending on the clarified persistence rule. - admin can access the Users section. - standard user cannot see admin-only navigation. - user list empty/loading/error states render. - create/edit user workflows render with validation feedback. - mobile viewport can complete core admin user-management navigation. - Dev Console Phase 1 is visible only when admin-authenticated and explicitly enabled in local/dev mode. - Dev Console Phase 1 can display tmux/Codex/workflow status and support trusted local/dev interaction when enabled. - Remote Dev Operator can view requirements/chunks/work packages, workflow state, summaries, session output, and recent reports from a phone or iPad viewport. - Remote Dev Operator can submit a short prompt/instruction or trigger an approved safe workflow transition in local/dev mode. - Telegram remains available or documented as a parallel/fallback operator channel where applicable. - Dev Console is blocked or unavailable in production-mode checks. - Future operator sanity checks should cover: - a human can find the theme switcher. - a human can understand which theme is active. - a human can find admin user-management workflows. - a human can tell whether Dev Console is privileged local/dev operator tooling. - a human can see the visible local/dev privileged-mode label before using Dev Console interaction. - a human can understand how Web Console and Telegram relate as remote operator channels. - setup and verification steps are documented without hidden credentials. ## Test Impact - Behavior Changed: None in this intake pass; this is requirements documentation only. - Existing Tests Affected: None. - New Tests Required: Future implementation chunks should add frontend component/browser smoke coverage for themes, admin navigation, user-management UX, Remote Dev Operator Console visibility/gating/mobile interaction, and Telegram/Web Console helper alignment when relevant. - Regression Risks: Theme refactors may break existing responsive shell behavior, admin visibility, form usability, or mobile layout. Dev Console scope could create serious security risk if environment gating, admin authentication, privileged-mode labeling, or production exclusion fails. - Runtime Smoke Needed: Not applicable for this requirements-only pass; required for later UI/theme/admin implementation chunks. - Frontend/Browser Coverage Needed: Future chunks need browser feedback for theme switching, mobile responsiveness, admin nav visibility, admin user-management flows, phone/iPad remote-operator workflows, Dev Console local/dev gating, and production-unavailable behavior. - Backend/API Coverage Needed: Future admin user-management UI chunks may rely on existing backend/API tests for user fields, role changes, setup credential behavior, and admin-only access. New backend coverage is required only if backend behavior changes. - Scenario/Workflow Coverage Needed: Future workflow planning should group the work into one phased work package with independently reviewable chunks or milestones for UI foundation, admin UX, Remote Dev Operator Console operability/safety, and Telegram/Web Console helper alignment. - Not-Applicable Rationale: No app behavior is changed by this requirements intake pass. ## Risks - Dev Console could become a severe security risk if privileged local/dev command execution, shell access, or tmux/Codex control is exposed without explicit environment gating, admin authentication, visible local/dev labeling, and production exclusion. - Remote operation over LAN/VPN/Tailscale can still expose powerful controls if the network, devcontainer, or admin session is misconfigured. - Mobile/iPad operation could create usability or accidental-action risks for approvals and command submission if confirmation and layout are weak. - A theme or component cleanup could accidentally rewrite the frontend architecture instead of building a focused foundation. - Replacing or bypassing existing PrimeNG/Tailwind patterns could increase scope and dependency risk. - Theme switching can create accessibility regressions if contrast, focus, and disabled states are not checked in each theme. - Mobile-first behavior could regress if desktop/admin layouts are prioritized without viewport testing. - Admin user-management UI could imply backend capabilities that are not actually implemented or safe. - Avatar handling can expand into file upload/storage/security scope if not explicitly constrained. - Hidden local/dev assumptions could make QA or human verification unreliable if feature flags, environment guards, Tailscale/VPN assumptions, and operator setup steps are not documented. ## Requirements Intake Notes - Requirements Intake Pass 1 created an active requirements draft from the rough idea. - The draft is intentionally `BLOCKED` for user clarification because several product and security decisions affect review readiness: - theme persistence and switcher scope. - component strategy around PrimeNG/local wrappers. - admin navigation structure. - user setup credential and avatar behavior. - Dev Console Phase 1 inclusion and safety boundaries. - browser smoke and visual acceptance expectations. - Requirements Intake Pass 2 applied clarified assumptions: - mixed PrimeNG plus thin local wrapper component strategy. - authenticated-user theme switching with browser-local persistence. - Classic as current visual direction rather than pixel-perfect preservation. - responsive header/dropdown/section navigation. - existing setup credential mechanism and initials/generated avatar defaults. - Dev Console as privileged local/dev admin/operator tooling with command/session interaction allowed only behind explicit environment gating. - LAN/VPN/Tailscale development access allowed; public internet and production exposure forbidden. - practical accessibility checks and browser smoke/screenshots for theme/admin states. - Requirements Intake Pass 3 refined the Dev Console into a Remote Dev Operator Console: - phone/iPad workflows over LAN/VPN/Tailscale are explicit. - workflow artifact/state viewing, tmux/Codex output inspection, prompt/instruction submission, and safe workflow transitions are Phase 1 local/dev goals. - Telegram is documented as a parallel/fallback remote-control path that should share workflow helpers where practical. - future broader exposure requires stronger auth/session controls, audit logs, command confirmations, role separation, network exposure controls, and secret hygiene. - No product code, chunks, package changes, environment changes, or app source changes were made. ## Requirements Review - Verdict: PASS. - Blockers: None. - Completeness: Requirements are complete enough for chunk planning. User perspectives, workflows, UI foundation scope, admin UX expectations, Remote Dev Operator Console behavior, Telegram relationship, permissions/auth boundaries, out-of-scope items, risks, acceptance criteria, and test impact are explicit. - Scope Split Recommendation: Use one phased work package only if the Chunk Planner splits it into small milestones: - Milestone 0: frontend/UI architecture and theme/component foundation decisions. - Milestone 1: Lumen/Railnight/Classic theme tokens, switcher, persistence, and app-shell preservation. - Milestone 2: admin navigation and user-management UX improvements. - Milestone 3: Remote Dev Operator Console local/dev gated foundation and workflow-state visibility. - Milestone 4: remote interaction, Codex/tmux prompt/session controls, Telegram alignment, and mobile/iPad operator smoke. If planning cannot keep those milestones independently reviewable, split Remote Dev Operator Console into a separate approved work package before implementation. - Security/Safety Assessment: PASS for planning. Full shell/tmux/Codex interaction is acceptable only because requirements constrain it to trusted local/dev mode, admin authentication, explicit feature flag/environment guard, visible privileged-mode labeling, LAN/VPN/Tailscale development access, and no production or public internet exposure. Future broader exposure requires dedicated security review, stronger auth/session controls, audit logs, command confirmation, role separation, network exposure controls, and secret hygiene. - Chunk-Planning Readiness: PASS. UI foundation/admin UX requirements are clear enough for chunk planning, and PrimeNG plus thin local wrapper strategy is sufficiently constrained. Mobile/iPad remote-operator workflows are testable through browser smoke and operator sanity checks. - Risks: Primary risks are scope size, accidental production exposure of privileged tooling, hidden environment assumptions, mobile accidental-action UX, and UI architecture drift. These risks are documented and should become chunk-level stop conditions and Test Impact requirements. - Required Changes: None before approval. Chunk planning must preserve the safety boundaries and milestone split above. - Recommended Next Action: Approve requirements, then run Chunk Planner. ## Chunk Plan - Work Package: `ai/work-packages/active/work-package-000002-ui-foundation-admin-experience.md` - Planning Path: A - Requirements Intake -> Requirements Review -> Chunk Planner -> Work Package -> Orchestrator. - Chunk Autopilot: enabled. - Stop Milestones: final_review. - Approved Chunk Queue: 1. `ai/chunks/backlog/chunk-000059-ui-foundation-architecture-operability-plan.md` 2. `ai/chunks/backlog/chunk-000060-theme-token-app-shell-foundation.md` 3. `ai/chunks/backlog/chunk-000061-ui-foundation-components.md` 4. `ai/chunks/backlog/chunk-000062-admin-navigation-user-management-ux.md` 5. `ai/chunks/backlog/chunk-000063-remote-dev-console-visibility.md` 6. `ai/chunks/backlog/chunk-000064-remote-dev-console-interaction.md` 7. `ai/chunks/backlog/chunk-000065-ui-admin-remote-operator-final-smoke.md` - Scope Split: - One phased work package is accepted because each milestone is independently reviewable. - Remote Dev Operator Console chunks are isolated into visibility and interaction phases with explicit local/dev gating and production-unavailable checks. - Autopilot Commit Policy: - Chunk Autopilot may run Developer/QA loops. - Orchestrator must ask human approval before each commit in this run. - Auto-merge/release is not allowed. ## Pass History ### Requirements Intake Pass 1 - Role: Requirements Intake - Date: 2026-05-11 - Goal: Turn the rough UI foundation, theming, admin user-management, and Dev Console idea into clear requirements. - Result: Drafted active requirements and marked them blocked for clarification. - Blockers: Theme persistence/switcher scope, component strategy, admin navigation, setup credential/avatar behavior, Dev Console Phase 1 scope/safety, and visual/browser validation expectations need clarification. - Validation: `bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh` passed; `ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md || true` passed and reported requirements intake needs clarification; `ai/commands/workflow-summary.sh || true` passed. - Cleanup: Not applicable. - Recommended Next Action: User clarification. ### Requirements Intake Pass 2 - Role: Requirements Intake - Date: 2026-05-11 - Goal: Resolve open questions using pragmatic local/dev operator assumptions and move requirements toward review readiness. - Result: Revised requirements to define theme persistence, component strategy, admin navigation, setup/avatar defaults, Dev Console privileged local/dev behavior, LAN/VPN/Tailscale assumptions, and validation expectations. Requirements are ready for Requirements Review but not approved. - Blockers: None from Requirements Intake. - Validation: `bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh` passed; `ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md || true` passed and reported `PENDING REQUIREMENTS REVIEW` with no gate blockers; `ai/commands/workflow-summary.sh || true` passed. - Cleanup: Not applicable. - Recommended Next Action: Requirements Review. ### Requirements Intake Pass 3 - Role: Requirements Intake - Date: 2026-05-11 - Goal: Refine Dev Console requirements around the larger remote-development operator workflow. - Result: Reframed Dev Console as a Remote Dev Operator Console for trusted local/dev use from phone or iPad over LAN/VPN/Tailscale, added workflow artifact/state viewing, tmux/Codex output inspection, prompt/instruction submission, safe workflow transition goals, Telegram fallback alignment, and future hardening requirements. Requirements remain ready for Requirements Review but not approved. - Blockers: None from Requirements Intake. - Validation: `bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh` passed; `ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md || true` passed and reported `PENDING REQUIREMENTS REVIEW` with no gate blockers; `ai/commands/workflow-summary.sh || true` passed. - Cleanup: Not applicable. - Recommended Next Action: Requirements Review. ### Requirements Review Pass 1 - Role: Requirements Review - Date: 2026-05-11 - Goal: Adversarially review UI foundation, admin UX, and Remote Dev Operator Console requirements for completeness, safety, scope control, and planning readiness. - Verdict: PASS. - Blockers: None. - Completeness: User workflows, functional requirements, UI/UX expectations, permissions/auth boundaries, Dev Console local/dev constraints, Telegram alignment, runtime smoke expectations, Test Impact, risks, and out-of-scope boundaries are complete enough for planning. - Security/Safety: PASS for planning. Full shell/tmux/Codex access is acceptable only under trusted local/dev feature-gated conditions with admin authentication, visible privileged-mode labeling, LAN/VPN/Tailscale development assumptions, production/public exposure forbidden, and future broader exposure requiring dedicated security review. - Scope Split: One phased work package is acceptable if split into independently reviewable milestones for UI foundation, theme/app shell, admin UX, Remote Dev Operator Console visibility, and remote interaction/Telegram alignment. Split Remote Dev Operator Console into a separate work package if chunk planning cannot keep it isolated. - Test Impact: PASS. Future chunks require browser/mobile smoke, operator sanity checks, local/dev gating checks, production-unavailable checks, admin visibility checks, and workflow-helper alignment checks. - Validation: `bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh` passed; `ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md || true` passed and reported Requirements Review `PASS` with no gate blockers; `ai/commands/workflow-summary.sh || true` passed; `git status --short --untracked-files=all` completed; `git diff --stat` completed. - Cleanup: Not applicable. - Recommended Next Action: Approve requirements, then run Chunk Planner. ### Chunk Planning Pass 1 - Role: Chunk Planner - Date: 2026-05-11 - Goal: Create phased work package and implementation chunk plan from approved UI Foundation/Admin Experience requirements. - Result: Created active work package `ai/work-packages/active/work-package-000002-ui-foundation-admin-experience.md` and seven approved backlog chunks covering architecture, theme/app shell, UI primitives, admin UX, Remote Dev Operator visibility, remote interaction/helper alignment, and final package smoke/report. - Blockers: None. - Validation: `ai/commands/requirements-state.sh ai/requirements/approved/requirements-000002-ui-foundation-admin-experience.md` passed before planning. - Cleanup: No runtime artifacts, `.tmp`, `.env`, local DB files, servers, product code, or package changes were created. - Recommended Next Action: Orchestrator starts Chunk Autopilot with `ai/chunks/backlog/chunk-000059-ui-foundation-architecture-operability-plan.md`. ## Handoff - Canonical State: chunk_planning - Gate Checked: ai/commands/requirements-state.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md - Result: passed - Blockers: None. - Recommended Next Action: Approve requirements, then run Chunk Planner. - Immediate Next Step: Approve requirements. - Human Review Command: not_applicable - Prompt Handoff Command: not_applicable - Transition Command: ai/commands/approve-requirements.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md - Post-Approval Command: ai/commands/approve-requirements.sh ai/requirements/active/requirements-000002-ui-foundation-admin-experience.md - Advisory Git Commands: not_applicable - Optional Prompt Review Command: not_applicable - Human Approval Needed: yes - approval moves requirements to approved lifecycle state.