implemented agents, readme, and changelog md files for ai-assisted

development.

AGENTS.md

@@ -0,0 +1,188 @@
+# AGENTS.md — ForgeBucket AI Agent Guide
+
+This file is for AI coding agents (Claude Code, GitHub Copilot, etc.) working in this repository. Read it before making changes.
+
+---
+
+## Mission
+
+ForgeBucket is a **unified operating system for software delivery** — not a Git repository viewer with CI attached. The guiding philosophy:
+
+> Repositories are runtime systems. The dashboard is a command center. GitOps is first-class.
+
+Every feature decision should answer: does this reduce cognitive load? Does this improve operational awareness? Does this improve developer flow?
+
+The full product vision lives in [`ai_agent_master_prompt_for_building_modern_git_platform.md`](ai_agent_master_prompt_for_building_modern_git_platform.md).
+
+---
+
+## Architecture Map
+
+```
+cmd/forgebucket/          — binary entry point (main.go)
+internal/
+  api/
+    router.go             — Chi router, all route definitions (~26 routes)
+    middleware/           — auth, CSRF, RBAC, logging
+    handlers/             — one file per domain (repo, pr, issue, auth, user, ssh...)
+  domain/
+    git/                  — sanitized git binary wrapper (exec.Command only, no shell)
+    federation/           — ActivityPub / ForgeFed (DATA LAYER ONLY — no handlers yet)
+    ci/                   — CI orchestrator (EMPTY — Phase 2 stub)
+  models/                 — XORM structs + 7 migration files
+  config/                 — ENV-driven config, fails fast on missing secrets
+web/                      — //go:embed target for the built React SPA
+frontend/
+  src/
+    pages/                — 20 route-level page components
+    components/           — shared UI (AppShell, Sidebar, Header, DiffViewer, etc.)
+    ui/
+      tokens.ts           — SINGLE SOURCE OF TRUTH for all design tokens
+    hooks/                — custom React hooks
+    api/                  — typed API client (fetch wrappers)
+```
+
+**Middleware chain — this order is fixed, do not reorder:**
+```
+Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
+```
+
+---
+
+## Current Phase Status
+
+Understand the phases before adding code — don't build Phase 3 infrastructure when Phase 2 is incomplete.
+
+| Phase | Scope | Status |
+|-------|-------|--------|
+| 1 | Auth, Git HTTP, repos, PRs, issues, RBAC, webhooks model, LFS, design system, 20-page SPA | **Complete** |
+| 2 | CI/CD orchestrator, runner manager, pipeline DAG visualization, artifact registry | **Active — `internal/domain/ci/` is the stub** |
+| 3 | GitOps controller, environments, drift detection, federation handlers, observability, audit log | Planned |
+| 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned |
+
+Do not implement Phase 3+ features without explicit discussion. The `domain/federation/` and `domain/ci/` directories are intentional stubs.
+
+---
+
+## Go Conventions
+
+### Git commands — critical rule
+Always use `exec.Command("git", arg1, arg2, ...)` with **discrete arguments**. Never build a shell string from user input.
+
+```go
+// CORRECT
+cmd := exec.Command("git", "clone", "--bare", repoURL, destPath)
+
+// WRONG — never do this
+cmd := exec.Command("sh", "-c", "git clone "+userInput)
+```
+
+This rule is non-negotiable. It prevents command injection.
+
+### Router / handlers
+- Chi router. Route definitions in `internal/api/router.go`.
+- One handler file per domain area. Keep handlers thin — business logic belongs in domain packages.
+- All POST/PUT/DELETE routes require `X-CSRF-Token` header matching the session cookie. The middleware enforces this, but don't remove it from routes.
+
+### Database
+- XORM for all DB access. Structs in `internal/models/`.
+- Migrations are numbered files in `internal/models/migrations/`. Always add a new migration file; never edit existing ones.
+- No raw SQL strings built from user input.
+
+### Secrets and config
+- All secrets come from environment variables via `internal/config/`.
+- Never hardcode secrets, tokens, or credentials anywhere.
+- `SESSION_SECRET` ≥ 32 chars. `CSRF_SECRET` = exactly 32 chars.
+
+### Error handling
+- Return errors up the call stack. Don't swallow them silently.
+- HTTP handlers use consistent JSON error responses — follow the pattern in existing handlers.
+
+---
+
+## TypeScript / React Conventions
+
+### Design tokens — critical rule
+All spacing, color, and sizing values must come from `frontend/src/ui/tokens.ts`. Do not introduce new hardcoded pixel values or color hex codes.
+
+```tsx
+// CORRECT — use token classes via Tailwind
+<div className="p-sm gap-xs">
+
+// WRONG — arbitrary values
+<div style={{ padding: "12px" }}>
+```
+
+### Grid system
+- Base unit: 8px. All spacing is multiples of 4px (`xs`) or 8px (`sm`).
+- Touch targets: 44px minimum height/width on all interactive elements (buttons, links, icon buttons).
+
+### Dark mode
+- Use Tailwind v4 `@variant dark` — not hardcoded dark: classes unless inside a component that explicitly handles both.
+- Colors must work in both light and dark modes. Test both.
+
+### Component patterns
+- `AppShell` wraps all authenticated pages. Don't bypass it.
+- `Sidebar` has three states: expanded (320px), collapsed (56px), mobile bottom bar. Respect all three.
+- Mobile-first: design for 375px, enhance for 1440px. Use the `BottomTabBar` for mobile nav — don't add new nav patterns.
+- Loading states: use `Skeleton` components for perceived performance, not spinners.
+- Mobile code review: use the `MobileComment` bottom-sheet pattern — not modals.
+
+### API calls
+- Use the typed API client in `frontend/src/api/` — don't write raw `fetch` calls in components.
+- Always include `X-CSRF-Token` header on mutating requests.
+
+---
+
+## What NOT to Do
+
+- **No shell string injection** — see Go conventions above
+- **No hardcoded secrets** — everything via env
+- **No skipping CSRF** — all mutating routes require it
+- **No arbitrary design values** — tokens.ts is the law
+- **No Phase 3+ features without discussion** — don't wire up GitOps, federation handlers, or the command palette until Phase 2 is complete
+- **No new color tokens** — if the design requires a new color, discuss it; don't invent one
+- **No modal-heavy UX** — this platform uses progressive disclosure; avoid deep modal chains
+- **No YAML-centric UI** — pipeline and environment config should feel operational, not config-file editing
+
+---
+
+## Testing
+
+```bash
+make test     # Go tests (go test ./...) + Vitest (frontend unit tests)
+make lint     # go vet + ESLint
+```
+
+- Go: test files live alongside source files (`*_test.go`)
+- Frontend: Vitest for unit tests, component tests alongside components
+- All UI changes must be manually verified at 1440px desktop and 375px mobile
+
+---
+
+## Key Files Reference
+
+| File | Purpose |
+|------|---------|
+| `internal/api/router.go` | All route definitions — start here for backend |
+| `internal/models/` | XORM models + migrations — all DB schemas |
+| `internal/config/config.go` | Env-driven config, required vars |
+| `internal/domain/git/` | Git binary wrapper — safe exec patterns |
+| `frontend/src/ui/tokens.ts` | Design token source of truth |
+| `frontend/src/components/AppShell.tsx` | Root layout wrapper |
+| `frontend/src/components/Sidebar.tsx` | 3-state navigation sidebar |
+| `frontend/src/pages/` | All 20 route-level pages |
+| `frontend/src/api/` | Typed API client |
+| `.env.example` | All required environment variables |
+| `CLAUDE.md` | Developer guide (rules overlap with this file — CLAUDE.md takes precedence on conflicts) |
+
+---
+
+## Running Locally
+
+```bash
+cp .env.example .env     # fill SESSION_SECRET and CSRF_SECRET
+make docker-up           # PostgreSQL via Docker Compose
+make migrate             # run XORM migrations
+make dev                 # Go :8080 + Vite :5173
+```

CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to ForgeBucket are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Planned — Phase 2 (CI/CD)
+- CI orchestrator with DAG pipeline execution
+- Runner manager (Docker, Kubernetes, Firecracker backends)
+- Pipeline DAG visualization (visual dependency graph with live execution state)
+- Build artifact storage and retention policies
+- Forgejo Actions gRPC integration
+- Flaky test detection
+- Pipeline log viewer (collapsible, filterable, syntax-highlighted)
+- Matrix builds and reusable workflow templates
+- Concurrency controls and pipeline cancellation
+
+### Planned — Phase 3 (GitOps + Observability + Federation)
+- GitOps controller with reconciliation loops
+- Environment management and topology visualization
+- Drift detection and sync status
+- Deployment promotion workflows (dev → staging → production)
+- Rollback visualization and one-click rollbacks
+- Canary and blue/green deployment support
+- Unified operational timeline (commits + deployments + incidents + CI failures merged)
+- ActivityPub / ForgeFed federation handlers (inbox, outbox, cross-instance PRs)
+- Audit log (all administrative and git-over-HTTP actions)
+- Secret scanning and dependency vulnerability scanning
+
+---
+
+## [0.1.0] — 2026-05-11
+
+Initial development milestone. Core Git hosting, collaboration, and frontend SPA are functional.
+
+### Added — Authentication & Security
+- User registration and login with secure session cookies
+- CSRF protection on all mutating routes via `X-CSRF-Token` header
+- Middleware chain: Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
+- SSH key management per user
+- OIDC / OAuth2 optional integration (configurable via env)
+- Scoped access tokens with optional expiration dates
+- Repository deploy keys (read-only or read-write HTTP tokens)
+- ENV-driven config with fail-fast validation on missing secrets
+
+### Added — Git Hosting
+- Smart HTTP transport (git clone, push, pull over HTTP)
+- AGit protocol support (`refs/for/` push for instant PR creation without branch switching)
+- Branch management (list, create, delete, default branch configuration)
+- Commit log and diff viewing
+- Git LFS per-repository (configurable file size limits, locking)
+- Branch protection rules (force-push blocking, required reviews)
+- Repository visibility (public / private)
+
+### Added — Collaboration
+- Pull requests (open / merged / closed states) with author tracking
+- Issues (open / closed)
+- Reviewer assignment (default reviewer per repo, per-PR reviewer assignment)
+- Merge strategy selection per repository (merge commit / squash / rebase)
+- Branching model configuration (feature / bugfix / release / hotfix prefixes)
+- PR default description templates (per-repo)
+- Excluded files from diffs (glob pattern configuration)
+- Webhook system with event filtering (push, pull_request, issue)
+- Repository member RBAC (read / write / admin roles)
+
+### Added — Frontend SPA
+- React 18 + TypeScript + Vite, embedded into Go binary via `//go:embed`
+- 20 route-level pages: Login, Register, Dashboard, Repos, CreateRepo, ImportRepo, Repo, RepoSettings, Blob, Commits, Branches, RepoIssues, RepoPRs, CreatePR, PRDetail, Starred, PRs (cross-repo), Pipelines (placeholder), Explore, Profile, Settings
+- AppShell layout wrapper for all authenticated pages
+- Triple-state sidebar: expanded (320px) / collapsed (56px) / mobile bottom bar
+- Mobile-first responsive design (375px → 1440px)
+- DiffViewer: side-by-side and unified views with syntax highlighting
+- MobileComment: bottom-sheet overlay for inline code review on mobile
+- TreeBrowser: repository file tree navigation
+- PipelineWaterfall: placeholder pipeline visualization component
+- Skeleton loading states for perceived performance
+
+### Added — Design System
+- Custom semantic token palette in `frontend/src/ui/tokens.ts`
+- Full dark/light mode support via Tailwind CSS v4 `@variant dark`
+- Brand colors: `#0052CC` (light) / `#3B82F6` (dark)
+- 8px grid system (xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, xxl: 48px)
+- 44px minimum touch targets on all interactive elements (WCAG 2.5.5)
+- Consistent border radius scale (subtle 3–8px, full 9999px)
+- System font stack (Segoe UI, Roboto, sans-serif)
+
+### Added — Infrastructure
+- PostgreSQL + XORM with 7 migration files covering: users, repositories, issues, SSH keys, access tokens, deploy keys, workflows, and LFS settings
+- ActivityPub actor data model (FederationActor with inbox/outbox URLs and RSA key pairs) — data layer only
+- Docker Compose setup for local PostgreSQL
+- Makefile targets: dev, build, migrate, test, lint, docker-up
+- WebSockets foundation for live logs and notifications
+
+---
+
+[Unreleased]: https://github.com/forgeo/forgebucket/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/forgeo/forgebucket/releases/tag/v0.1.0

README.md

@@ -1,101 +1,231 @@
-# ForgeBucket 🛡️🪣
+# ForgeBucket
 
-**Sovereign Federation meets Enterprise Design.**
+> A unified operating system for software delivery — not just a Git host.
 
-ForgeBucket is a production-ready, federated git collaboration platform. It combines the high-performance, lightweight Go engine of **Forgejo** with the sophisticated, high-density UI/UX of **Bitbucket**, optimized for a "Responsive-First, Access Anywhere" experience.
+ForgeBucket is a self-hosted, federated developer operations platform. Where other Git platforms show you a list of files, ForgeBucket surfaces deployments, pipeline health, environment drift, and operational context directly alongside your code. Repositories are runtime systems. The dashboard is a command center.
+
+**Status:** Early development. Core Git hosting, collaboration, and auth are functional. CI/CD and GitOps integrations are next.
 
 ---
 
-## 🚀 The Vision
+## What Makes It Different
 
-ForgeBucket aims to provide developers with a world-class code review and project management experience without sacrificing data sovereignty. It bridges the gap between community-driven open-source software and enterprise-grade usability.
-
-- **Engine:** Built on the Forgejo/Gitea ecosystem.
-- **Interface:** Powered by Atlassian Design System (ADS) principles.
-- **Connectivity:** Full ActivityPub (ForgeFed) integration for a decentralized git world.
+| Principle | What it means |
+|-----------|---------------|
+| **Repositories are runtime systems** | Repo pages show deployments, environments, health, and risk — not just a file tree |
+| **Operational awareness by default** | Failing pipelines, stale PRs, security alerts, and environment drift surface without digging |
+| **GitOps is first-class** | Git is the source of truth for deployment state, rollbacks, and environment promotion |
+| **Keyboard-first UX** | Global command palette, minimal navigation depth, low cognitive load |
+| **Federated by design** | ActivityPub (ForgeFed) for cross-instance pull requests and collaboration |
+| **Sovereign** | Fully self-hostable — your code, your infrastructure, your keys |
 
 ---
 
-## 🛠️ Tech Stack
+## Feature Status
 
-### Backend & Core
+### Core Platform
+| Feature | Status |
+|---------|--------|
+| User auth (registration, login, sessions) | Done |
+| CSRF + session security | Done |
+| SSH key management | Done |
+| OIDC / OAuth2 (optional) | Done |
+| Access tokens (scoped, expiring) | Done |
+| Deploy keys | Done |
 
-- **Language:** Go (Golang) 1.21+
-- **Database:** PostgreSQL with XORM
-- **Git Engine:** Native System Git Binary execution
-- **CI/CD:** Forgejo Actions (gRPC protocol)
+### Git Hosting
+| Feature | Status |
+|---------|--------|
+| Smart HTTP transport (clone/push/pull) | Done |
+| AGit protocol (`refs/for/` PR creation) | Done |
+| Branch management | Done |
+| Commit + diff viewing | Done |
+| Git LFS (per-repo, configurable size limits) | Done |
+| Branch protection rules | Done |
 
-### Frontend & UX
+### Collaboration
+| Feature | Status |
+|---------|--------|
+| Pull requests (open/merged/closed) | Done |
+| Issues | Done |
+| Code review (inline comments, mobile bottom-sheet) | Done |
+| Side-by-side + unified diff viewer | Done |
+| Reviewer assignment | Done |
+| Merge strategies (merge/squash/rebase) | Done |
+| Webhooks | Done (model + routes) |
+| Repository RBAC (read/write/admin) | Done |
 
-- **Framework:** React 18+ (Embedded in Go binary)
-- **Styling:** Tailwind CSS + Atlassian Design Tokens
-- **Components:** Custom implementation of Atlaskit primitives
-- **Real-time:** WebSockets for live logs and notifications
+### CI/CD
+| Feature | Status |
+|---------|--------|
+| Pipeline DAG visualization | In progress |
+| CI orchestrator | Planned (Phase 2) |
+| Runner manager | Planned (Phase 2) |
+| Artifact registry | Planned (Phase 2) |
+| Forgejo Actions integration (gRPC) | Planned (Phase 2) |
+| Flaky test detection | Planned (Phase 2) |
+
+### GitOps + Environments
+| Feature | Status |
+|---------|--------|
+| GitOps controller | Planned (Phase 3) |
+| Environment management | Planned (Phase 3) |
+| Drift detection | Planned (Phase 3) |
+| Deployment promotion workflows | Planned (Phase 3) |
+| Rollback visualization | Planned (Phase 3) |
+| Canary / blue-green support | Planned (Phase 3) |
+
+### Observability + Security
+| Feature | Status |
+|---------|--------|
+| Unified operational timeline | Planned (Phase 3) |
+| Secret scanning | Planned (Phase 3) |
+| Dependency scanning | Planned (Phase 3) |
+| Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) |
+| Audit log | Planned (Phase 3) |
+
+### Federation
+| Feature | Status |
+|---------|--------|
+| ActivityPub actor model | Done (data layer) |
+| Federation handlers / inbox / outbox | Planned (Phase 3) |
+| Cross-instance pull requests | Planned (Phase 3) |
 
 ---
 
-## ✨ Key Features
-
-- **Responsive Navigation:** A triple-state sidebar (Expanded, Collapsed, Mobile Bottom-Bar) that adheres to an 8px grid system.
-- **Advanced Diff Viewer:** Side-by-side and unified views with "Bottom Sheet" comment overlays for mobile code reviews.
-- **Federated Pull Requests:** Interaction across different ForgeBucket/Forgejo instances via ActivityPub.
-- **AGit "Quick Edit":** Web-based file editing with automatic `refs/for/` branch creation for instant PRs.
-- **Skeleton Loading:** Optimized "Perceived Performance" using pulsate loading states for metadata.
-
----
-
-## 🔒 Security & Compliance
-
-- **OWASP Top 10 Compliance:** Strict protection against XSS, CSRF, and SQLi.
-- **Command Sanitization:** Hardened wrapper for all Git binary executions.
-- **Identity:** OIDC and OAuth2 support with Row-Level Security (RLS) mentalities.
-- **Auditability:** Full logging of all administrative and git-over-HTTP actions.
-
----
-
-## 🏁 Getting Started
-
-### Prerequisites
-
-- Go 1.21 or higher
-- Node.js 18+ (for frontend development)
-- PostgreSQL 14+
-- System Git 2.20+
-
-### Installation
-
-1. **Clone the repository:**
+## Quick Start
 
 ```bash
-   git clone [https://github.com/your-repo/forgebucket.git](https://github.com/your-repo/forgebucket.git)
+# 1. Clone and configure
+git clone https://github.com/forgeo/forgebucket.git
 cd forgebucket
+cp .env.example .env          # fill in SESSION_SECRET and CSRF_SECRET
+
+# 2. Start PostgreSQL
+make docker-up
+
+# 3. Run DB migrations
+make migrate
+
+# 4. Start both servers (Go :8080 + Vite :5173)
+make dev
 ```
 
-2. **Setup Frontend:**
+The Go API runs at `http://localhost:8080`. The Vite dev server runs at `http://localhost:5173` and proxies API requests.
 
-```Bash
-cd frontend
-npm install
-npm run build
+---
+
+## Architecture
+
+```
+ForgeBucket
+├── API Gateway          (Chi router, internal/api/)
+├── Auth Service         (sessions, CSRF, OIDC — internal/api/handlers/)
+├── Repository Service   (git HTTP, branches, LFS — internal/domain/git/)
+├── Pull Request Service (PRs, reviews, merge — internal/api/handlers/)
+├── Issue Service        (issues, labels — internal/api/handlers/)
+├── Federation Layer     (ActivityPub actors — internal/domain/federation/)  ← stub
+├── CI Orchestrator      (pipeline scheduling — internal/domain/ci/)         ← stub
+├── Secret Manager       (env-based, scoped tokens — internal/config/)
+├── Database             (PostgreSQL + XORM — internal/models/)
+└── Web Frontend         (React 18 + TypeScript, embedded via //go:embed — web/)
 ```
 
-3. **Build the Binary:**
-
-```Bash
-cd ..
-go build -o forgebucket main.go
+**Middleware chain (every request):**
+```
+Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
 ```
 
-4. **Run:**
+---
 
-```Bash
-./forgebucket web
-```
+## Tech Stack
 
-## 🤝 Contributing
+| Layer | Technology |
+|-------|------------|
+| Language | Go 1.21+ |
+| Router | Chi |
+| ORM / Migrations | XORM + PostgreSQL |
+| Frontend framework | React 18 + TypeScript |
+| Build tool | Vite |
+| Styling | Tailwind CSS v4 |
+| Code editing | CodeMirror |
+| Real-time | WebSockets |
+| Container | Docker Compose (dev) |
+| Federation | ActivityPub / ForgeFed |
 
-We follow the "Responsive-First" contribution model. Please ensure all UI changes are tested on both Desktop (1440px) and Mobile (375px) breakpoints.
+---
 
-## 📄 License
+## Design System
 
-This project is licensed under the MIT License - see the LICENSE file for details. Portions of the code are derived from Forgejo (GPLv3).
+ForgeBucket has its own design language — intentionally distinct from GitHub and GitLab.
+
+**Philosophy:** information-dense but calm. Inspired by Linear, Datadog, and VS Code — not enterprise CRUD forms.
+
+- **Colors:** Semantic token palette with full dark/light mode. Brand blue `#0052CC` (light) / `#3B82F6` (dark). Source of truth: `frontend/src/ui/tokens.ts`
+- **Grid:** 8px base unit. All spacing is multiples of 4px (xs) or 8px (sm). No arbitrary pixel values.
+- **Touch targets:** 44px minimum on all interactive elements (WCAG 2.5.5)
+- **Navigation:** Triple-state sidebar (expanded 320px / collapsed 56px / mobile bottom bar). Keyboard-first.
+- **Breakpoints:** Desktop 1440px, mobile 375px. Mobile code review uses bottom-sheet overlays, not modals.
+- **Typography:** System font stack (Segoe UI, Roboto, sans-serif)
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string |
+| `SESSION_SECRET` | Yes | Session signing key, ≥ 32 chars (`openssl rand -hex 32`) |
+| `CSRF_SECRET` | Yes | CSRF key, exactly 32 chars (`openssl rand -hex 16`) |
+| `PORT` | No | HTTP port, default `8080` |
+| `REPO_ROOT` | Yes | Absolute path for bare git repository storage |
+| `INSTANCE_URL` | Yes | Public URL of this instance (no trailing slash) |
+| `INSTANCE_NAME` | No | Display name, default `ForgeBucket` |
+| `OIDC_ISSUER` | No | OIDC provider URL |
+| `OIDC_CLIENT_ID` | No | OIDC client ID |
+| `OIDC_CLIENT_SECRET` | No | OIDC client secret |
+| `DEBUG` | No | Disables Secure cookies, enables verbose logging |
+
+---
+
+## Common Commands
+
+| Command | What it does |
+|---------|-------------|
+| `make dev` | Start Go API + Vite dev server concurrently |
+| `make build` | Build frontend, embed into Go binary |
+| `make migrate` | Sync XORM schemas to PostgreSQL |
+| `make test` | Run Go tests + Vitest |
+| `make lint` | `go vet` + ESLint |
+| `make docker-up` | Start PostgreSQL via Docker Compose |
+
+---
+
+## Roadmap
+
+| Phase | Focus | Status |
+|-------|-------|--------|
+| Phase 1 | Core Git hosting, auth, PRs, issues, RBAC, design system | Done |
+| Phase 2 | CI/CD orchestrator, runner manager, pipeline visualization, artifact registry | In progress |
+| Phase 3 | GitOps controller, environments, observability, federation handlers, audit log | Planned |
+| Phase 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned |
+
+---
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for AI-assisted development conventions, architecture boundaries, and what not to build without discussion.
+
+All UI contributions must be tested at both 1440px desktop and 375px mobile. Spacing must use tokens from `frontend/src/ui/tokens.ts` — no arbitrary pixel values.
+
+---
+
+## Module Path
+
+`github.com/forgeo/forgebucket`
+
+---
+
+## License
+
+MIT License. See LICENSE for details.

ai_agent_master_prompt_for_building_modern_git_platform.md

@@ -0,0 +1,741 @@
+# MASTER IMPLEMENTATION PROMPT
+## Building a Modern Git Platform with CI/CD + GitOps + Operational UX
+
+You are an elite senior staff engineer, platform architect, DevOps architect, distributed systems engineer, and product UX engineer.
+
+You are tasked with designing and implementing a next-generation self-hosted Git platform.
+
+This platform exists in the category of:
+- GitHub
+- GitLab
+- Forgejo
+- Gitea
+- Bitbucket
+
+BUT:
+
+You must NOT merely clone existing platforms.
+
+The goal is to create:
+
+> a modern developer operations platform
+
+that deeply integrates:
+- Git hosting
+- pull requests
+- CI/CD
+- GitOps
+- deployments
+- environments
+- observability
+- security
+- operational awareness
+- developer productivity
+
+The platform should feel:
+- fast
+- operational
+- developer-first
+- low cognitive load
+- modern
+- reliable
+- modular
+- keyboard-first
+- context-aware
+
+The product philosophy is:
+
+> repositories are operational systems
+
+NOT:
+
+> collections of files.
+
+==================================================
+HIGH LEVEL PRODUCT GOALS
+==================================================
+
+The platform should optimize for:
+
+- immediate situational awareness
+- workflow continuity
+- deployment visibility
+- operational clarity
+- reliability
+- developer flow
+- observability
+- intelligent automation
+- security by default
+- excellent UX
+
+Users should always be able to answer:
+
+- what changed?
+- what failed?
+- what deployed?
+- what is unhealthy?
+- what needs my attention?
+- what environments are affected?
+- what should I review next?
+- what caused this incident?
+
+without navigating deeply.
+
+==================================================
+CORE PRODUCT PRINCIPLES
+==================================================
+
+1. UX FIRST
+
+Most Git platforms prioritize functionality over usability.
+
+This platform must prioritize:
+- readability
+- discoverability
+- contextual awareness
+- progressive disclosure
+- speed
+- low noise
+- operational understanding
+
+Avoid:
+- tab overload
+- enterprise clutter
+- giant forms
+- notification spam
+- YAML-centric UX
+- log-centric UX
+
+The system should feel:
+- intentional
+- calm
+- efficient
+- operationally intelligent
+
+--------------------------------------------------
+
+2. OPERATIONAL AWARENESS
+
+The platform must continuously surface:
+- failing pipelines
+- deployment health
+- environment drift
+- flaky tests
+- security issues
+- review bottlenecks
+- dependency risks
+- deployment risks
+
+This information should appear naturally throughout the UI.
+
+--------------------------------------------------
+
+3. REPOSITORIES ARE RUNTIME SYSTEMS
+
+The repository page should not simply display files.
+
+It should display:
+- deployments
+- environments
+- active PRs
+- operational health
+- timelines
+- incidents
+- ownership
+- risk
+- observability
+
+The file tree is secondary.
+
+--------------------------------------------------
+
+4. GITOPS IS FIRST CLASS
+
+Git should become:
+- source of truth
+- deployment history
+- environment state definition
+- rollback system
+- audit log
+
+The system must support:
+- reconciliation
+- drift detection
+- declarative environments
+- promotion workflows
+- rollback visualization
+- environment topology
+
+--------------------------------------------------
+
+5. RELIABILITY IS A PRIMARY FEATURE
+
+The platform should optimize for:
+- deterministic execution
+- idempotency
+- isolation
+- resilience
+- queue durability
+- observability
+- safe rollbacks
+- fault tolerance
+
+==================================================
+ARCHITECTURE REQUIREMENTS
+==================================================
+
+Design the platform using modular services.
+
+Suggested architecture:
+
+```txt
+Platform
+├── API Gateway
+├── Auth Service
+├── Repository Service
+├── Pull Request Service
+├── Issue Service
+├── Event Bus
+├── CI Orchestrator
+├── Runner Manager
+├── Artifact Registry
+├── Package Registry
+├── Deployment Engine
+├── GitOps Controller
+├── Environment Service
+├── Secret Manager
+├── Notification Service
+├── Search Service
+├── Observability Layer
+├── Metrics Service
+├── Audit Service
+└── Web Frontend
+```
+
+==================================================
+EVENT DRIVEN ARCHITECTURE
+==================================================
+
+The platform should be event-driven.
+
+Everything emits events.
+
+Examples:
+
+```txt
+repo.created
+push.created
+pr.opened
+review.requested
+pipeline.started
+pipeline.failed
+artifact.published
+deployment.started
+deployment.failed
+environment.drift_detected
+incident.created
+```
+
+Requirements:
+- durable events
+- replay support
+- auditability
+- timeline reconstruction
+- reactive UI updates
+
+Recommended technologies:
+- NATS
+- Kafka
+- RabbitMQ
+
+Prefer NATS initially for simplicity.
+
+==================================================
+CI/CD SYSTEM REQUIREMENTS
+==================================================
+
+The CI/CD system must support:
+
+- DAG pipelines
+- matrix builds
+- reusable workflows
+- workflow templates
+- conditional execution
+- parallel execution
+- artifacts
+- caches
+- retries
+- concurrency controls
+- cancellation
+- pipeline graphs
+- environment promotion
+- rollback support
+- preview environments
+- flaky test detection
+- deployment visualization
+
+The orchestrator should:
+- schedule
+- coordinate
+- monitor
+
+NOT directly execute jobs.
+
+==================================================
+RUNNER SYSTEM REQUIREMENTS
+==================================================
+
+Runners should:
+- be ephemeral
+- isolated
+- disposable
+- reproducible
+- stateless
+
+Support execution backends:
+
+1. Docker containers
+2. Kubernetes jobs
+3. Firecracker microVMs
+4. Bare metal runners
+
+Security is critical.
+
+Forked PRs must never automatically receive secrets.
+
+==================================================
+SECRET MANAGEMENT
+==================================================
+
+Implement scoped secret management.
+
+Secret hierarchy:
+
+```txt
+Global
+→ Organization
+→ Repository
+→ Environment
+→ Runtime ephemeral injection
+```
+
+Support:
+- Vault
+- OIDC federation
+- cloud secret providers
+- encrypted secret storage
+
+Secrets must:
+- never leak to logs
+- be masked automatically
+- support audit trails
+- support rotation
+
+==================================================
+ARTIFACT + PACKAGE MANAGEMENT
+==================================================
+
+Implement:
+- build artifact storage
+- OCI registry
+- package registries
+- retention policies
+- artifact provenance
+- signing support
+- SBOM support
+
+Support:
+- container images
+- npm
+- cargo
+- pip
+- maven
+- generic artifacts
+
+==================================================
+GITOPS REQUIREMENTS
+==================================================
+
+GitOps must be deeply integrated.
+
+Support:
+- reconciliation loops
+- drift detection
+- sync visualization
+- environment topology
+- deployment promotion
+- rollback flows
+- canary releases
+- blue/green deployments
+- environment history
+
+The UI should make GitOps understandable.
+
+Avoid overwhelming Kubernetes-centric UX.
+
+==================================================
+DATABASE + STORAGE DESIGN
+==================================================
+
+Separate:
+- application code
+- repository storage
+- artifacts
+- caches
+- logs
+- uploads
+
+Repository storage should NOT exist in the app repository.
+
+Recommended:
+
+```txt
+/data/repos
+/data/artifacts
+/data/cache
+/data/uploads
+```
+
+Repository storage is runtime instance data.
+
+Treat it like:
+- database files
+- object storage
+- runtime state
+
+==================================================
+DASHBOARD REQUIREMENTS
+==================================================
+
+The dashboard should behave like:
+
+> an operational command center
+
+NOT:
+
+> a repository list.
+
+Include:
+
+1. Attention Required
+- failing pipelines
+- stale PRs
+- security alerts
+- deployment failures
+- environment drift
+
+2. Active Workspaces
+- active repos
+- active branches
+- assigned reviews
+- recent deployments
+
+3. Team Activity
+- merges
+- releases
+- deployments
+- incidents
+
+4. CI/CD Overview
+- pipeline health
+- queue health
+- flaky tests
+- deployment status
+
+5. Review Dashboard
+- pending reviews
+- high risk PRs
+- stale reviews
+
+6. Security Overview
+- dependency vulnerabilities
+- secret leaks
+- suspicious pushes
+
+==================================================
+REPOSITORY PAGE REQUIREMENTS
+==================================================
+
+The repository page must feel operational.
+
+Top area should include:
+
+```txt
+Repo Name
+Production: Healthy
+CI: Passing
+Deployments: 3 active
+Risk: Medium
+```
+
+The page should include:
+
+- active PRs
+- deployments
+- environments
+- repository health
+- security alerts
+- ownership
+- recent activity
+- operational timeline
+- preview environments
+- CI/CD overview
+- deployment history
+
+The README should not dominate the page.
+
+==================================================
+UNIFIED OPERATIONAL TIMELINE
+==================================================
+
+Implement a unified timeline merging:
+- commits
+- deployments
+- incidents
+- rollbacks
+- CI failures
+- security events
+- alerts
+- releases
+
+This is one of the most important features.
+
+Users should easily answer:
+
+> what changed before things broke?
+
+==================================================
+PIPELINE UX REQUIREMENTS
+==================================================
+
+Pipelines should be visual DAGs.
+
+Support:
+- dependency visualization
+- execution timing
+- bottleneck detection
+- retry controls
+- artifact visibility
+- live execution state
+- grouped logs
+- semantic errors
+
+Logs should support:
+- filtering
+- collapsing
+- syntax highlighting
+- structured parsing
+- AI summarization
+
+==================================================
+DEPLOYMENT UX REQUIREMENTS
+==================================================
+
+Deployments must feel first-class.
+
+Each environment should expose:
+
+```txt
+Production
+Healthy
+v1.4.2
+3 pods
+0.1% errors
+Last deploy 14m ago
+```
+
+Support:
+- rollback
+- traffic shifting
+- canary visibility
+- deployment timelines
+- release notes
+- environment logs
+- health checks
+
+==================================================
+COMMAND PALETTE REQUIREMENTS
+==================================================
+
+Implement a global command palette.
+
+Inspired by:
+- VS Code
+- Raycast
+- Linear
+
+Examples:
+
+```txt
+/retry failed jobs
+/deploy staging
+/open logs
+/review next
+/show flaky tests
+/open production incidents
+```
+
+Keyboard-first navigation is critical.
+
+==================================================
+AI-ASSISTED FEATURES
+==================================================
+
+Implement optional AI-assisted operational tooling.
+
+Examples:
+
+- failure diagnosis
+- flaky test detection
+- architecture summaries
+- impact analysis
+- deployment risk scoring
+- review summaries
+- onboarding explanations
+
+Example:
+
+```txt
+Likely failure cause:
+Database migration introduced lock contention.
+```
+
+==================================================
+OBSERVABILITY REQUIREMENTS
+==================================================
+
+Integrate:
+- metrics
+- traces
+- logs
+- deployment state
+- incident state
+- service topology
+
+Do not isolate observability into external systems.
+
+Expose operational health directly in repository pages.
+
+==================================================
+RELIABILITY REQUIREMENTS
+==================================================
+
+Implement:
+- durable queues
+- retries
+- dead-letter queues
+- resumable pipelines
+- distributed scheduling
+- concurrency controls
+- checkpointing
+- idempotent operations
+
+The platform should survive:
+- runner crashes
+- orchestrator crashes
+- network partitions
+- deployment interruptions
+
+==================================================
+SECURITY REQUIREMENTS
+==================================================
+
+Implement:
+- signed artifacts
+- provenance verification
+- branch protections
+- permission scopes
+- audit logging
+- secret scanning
+- dependency scanning
+- runner isolation
+- sandboxing
+
+Support:
+- Sigstore
+- Cosign
+- SLSA concepts
+
+==================================================
+UI/UX DESIGN LANGUAGE
+==================================================
+
+The UI should feel:
+- modern
+- minimal
+- operational
+- clean
+- responsive
+- keyboard-first
+- information dense but calm
+
+Visual inspirations:
+- Linear
+- Datadog
+- Grafana
+- Raycast
+- Arc Browser
+- VS Code
+- modern observability dashboards
+
+Avoid:
+- clutter
+- giant tables
+- excessive modal workflows
+- deeply nested navigation
+
+==================================================
+IMPLEMENTATION EXPECTATIONS
+==================================================
+
+You should:
+- think deeply about architecture
+- optimize for maintainability
+- optimize for extensibility
+- prioritize UX heavily
+- prioritize reliability heavily
+- explain tradeoffs
+- avoid overengineering early
+- support future scalability
+
+You should continuously ask:
+
+- does this reduce cognitive load?
+- does this improve operational awareness?
+- does this improve developer flow?
+- does this improve reliability?
+- does this make debugging easier?
+
+==================================================
+DELIVERABLES
+==================================================
+
+When implementing features:
+
+Provide:
+- architecture reasoning
+- schema design
+- API design
+- event definitions
+- service boundaries
+- UI mockups
+- workflow diagrams
+- UX rationale
+- security implications
+- scaling considerations
+- operational implications
+
+Always optimize for:
+- clarity
+- reliability
+- developer experience
+- operational intelligence
+- future extensibility
+
+The platform should ultimately feel like:
+
+> a unified operating system for software delivery
+
+rather than:
+
+> a Git repository viewer with CI attached.