AGENTS.md

1# AGENTS.md - Frontend Coding Guidelines
2 
3## Engineering Workflow
4```bash
5bun install # ([bun.sh](https://bun.sh/docs/cli/install?utm_source=openai))
6bun run build # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))
7bun run dev # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))
8bun run lint # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))
9```
10 
11## Dependency Guide
12- **Overview**: Full dependency descriptions are maintained in `dependencies_overview.md`.
13- **Usage**: Keep this section concise and treat `dependencies_overview.md` as the source-of-truth dependency catalog.
14 
15## Business Logic Domain
16- **Summary**: This frontend models a Code Confluence platform that connects GitHub/GitLab repositories, collects metadata for ingestion jobs, and tracks workflow runs plus codebase status. It surfaces AI “agent” snapshot outputs (engineering workflows, dependency guides, business logic summaries, app interface scans) and stores user feedback tied to those runs. Supporting domains include credential/provider onboarding, model provider configuration (including OAuth), and tool configuration for integrations.
17- **Key domains**:
18  - Repository onboarding, provider credential handling, and multi-repository routing/metadata state.
19  - Workflow run tracking, agent snapshot storage, and presentation of Agent MD artifacts.
20  - Agent MD artifact formatting and markdown conversion for UI display.
21  - Model provider configuration, OAuth-based connections, and tool configuration for analysis pipelines.
22  - Feedback capture, rating/comment submission, and downstream issue reporting.
23- **Key data models & modules**:
24  - Agent feedback: `src/features/agent-feedback/api.ts`, `src/features/agent-feedback/schema.ts`, `src/features/agent-feedback/store.ts`, `src/types/agent-feedback.ts`.
25  - Agent snapshots & events: `src/features/repository-agent-snapshots/collection.ts`, `src/features/repository-agent-snapshots/hooks.ts`, `src/features/repository-agent-snapshots/schema.ts`, `src/features/repository-agent-snapshots/transformers.ts`, `src/types/agent-events.ts`.
26  - Agent MD artifacts: `src/lib/agent-md-to-markdown.ts`.
27  - Model configuration & OAuth: `src/features/model-config/provider-schema.ts`, `src/features/model-config/schema-generator.ts`, `src/features/model-config/types.ts`, `src/hooks/useCodexOauth.ts`, `src/hooks/useSaveModelConfig.ts`.
28  - Tool configuration: `src/features/tool-config/types.ts`, `src/hooks/useSaveToolConfig.ts`.
29  - Repository/provider APIs & routing: `src/lib/api.ts`, `src/lib/api/repositories-api.ts`, `src/lib/api/repository-provider-api.ts`, `src/lib/utils/provider-route-utils.ts`, `src/lib/utils/provider-utils.ts`, `src/types/repository-provider.ts`, `src/routeTree.gen.ts`.
30  - Credentials & auth state: `src/lib/validation/credential-schemas.ts`, `src/types/credential-enums.ts`, `src/lib/github-token-utils.ts`, `src/lib/env.ts`, `src/stores/useAuthStore.ts`.
31  - UI state & shared types: `src/hooks/use-data-table.ts`, `src/forms/types.ts`, `src/stores/useDevModeStore.ts`, `src/stores/useThemeStore.ts`, `src/types/data-table.ts`, `src/types/index.ts`, `src/types.ts`.
32- **Reference**: See `business_logic_references.md` for a detailed index of domain artifacts.
33 
34## Commands
35```bash
36bun install                      # Install dependencies
37vite                            # Dev server (http://localhost:5173)
38vite build                      # TypeScript check + build
39bun eslint .                    # Lint all files
40bun eslint src/path/file.tsx    # Lint single file
41```
42 
43## Code Style (from .cursor/rules)
44- **TypeScript**: Use interfaces over types, avoid enums (use maps), no `any` types, precise types always
45- **Functions**: Use `function` keyword for pure functions, functional/declarative patterns over classes
46- **Naming**: Descriptive with auxiliary verbs (isLoading, hasError), lowercase-with-dashes for directories
47- **Imports**: Preserve existing formatting, use `@/*` absolute path alias, use axios for HTTP (never fetch)
48- **Formatting**: Preserve existing code/comments unless necessary, curly braces for all conditionals
49- **Constraints**: Do not remove code/comments unless necessary, just do what's asked (ask before doing more)
50 
51## Architecture
52- **Stack**: React 19 + TypeScript + Vite + TanStack Router + TanStack Query + shadcn/ui + TailwindCSS
53- **Routing**: TanStack Router (file-based in `src/routes/`), `__root.tsx` redirects `/` to `/onboarding`
54- **State**: Zustand (client state), TanStack Query (server state, 5min stale), URL state via `useDataTableWithRouter`
55- **UI**: shadcn/ui components use CVA variants as props (`variant="outline"` NOT `variant={{ outline: true }}`)
56- **API**: Axios client in `src/lib/api.ts`, wrap all calls in TanStack Query hooks, dual error handling system
57- **Forms**: Tanstack Form
58- **Tables**: DiceUI + TanStack Table v8 with URL state sync via TanStack Router (NOT nuqs)
59 
60## File Structure
61`src/components/ui/` shadcn base | `src/components/custom/` business | `src/pages/` pages | `src/routes/` routes | `src/lib/` api/utils/env
62 
63## Operating Instructions
641. Use Context7 docs for dependency versions | Check existing code before changes | Structure: exported component → subcomponents → helpers → types
652. When in read mode always remember to raise access from user for any command that you want to execute.
66 
67<!-- intent-skills:start -->
68## Skill Loading
69 
70Before substantial work:
71- Skill check: run `npx @tanstack/intent@latest list`, or use skills already listed in context.
72- Skill guidance: if one local skill clearly matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
73- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
74- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
75<!-- intent-skills:end -->
76 
77<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:BEGIN -->
78<CRITICAL_INSTRUCTION>
79 
80> Generated from branch `dev` at commit `5ecdba39d57f50c5188a8e32b9dd4f52d01611fe` (2026-07-18). Content may become stale as new commits land.
81 
82</CRITICAL_INSTRUCTION>
83 
84## Engineering Workflow
85### Install
86- `bun install` — repository root; config: `package.json` and `bun.lock`
87 
88### Build
89- `bun run build` — repository root; config: `package.json` (`tsc -b && vite build`)
90 
91### Dev
92- `bun run dev` — repository root; config: `package.json` (`vite`)
93 
94### Test
95- Not detected
96 
97### Lint
98- `bun run lint` — repository root; config: `package.json`
99 
100### Type Check
101- `bunx tsc -b` — repository root; config: `tsconfig.json` and `package.json` (build script)
102 
103## Dependency Guide
104See [`dependencies_overview.md`](./dependencies_overview.md) for the full dependency catalog and usage notes.
105 
106## Business Domain
107### Description
108 
109This frontend is for a code analysis and repository operations platform centered on onboarding GitHub/GitLab repositories, ingesting them into workflow runs, and displaying AI agent snapshot outputs such as engineering workflows, dependency guides, business logic summaries, and app interface scans. It also covers model-provider and tool configuration, OAuth and credential handling, and feedback flows that turn app or agent feedback into GitHub issues.
110 
111### References
112 
113See [`business_domain_references.md`](./business_domain_references.md) for the supporting source references used to derive this domain summary.
114 
115## App Interfaces
116See [`app_interfaces.md`](./app_interfaces.md) for the canonical interface and endpoint reference.
117 
118## Architecture
119See [`architecture.md`](./architecture.md) for the canonical system architecture diagram.
120 
121<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:END -->
122