···11# Agent Notes
2233+## RTK Commands
44+55+When running shell commands, prefix them with `rtk` by default. If `rtk` has no
66+filter for a command, it passes through unchanged.
77+88+Examples:
99+1010+```bash
1111+rtk git status
1212+rtk git diff
1313+rtk rg "pattern" src
1414+rtk npm run build
1515+```
1616+1717+Rules:
1818+1919+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`.
2020+- Use `rtk rg` for searching, including TSX/JSX files.
2121+- Do not use `rtk sed`, `rtk proxy sed`, `rtk cat`, `rtk read`, or other RTK-filtered readers for `.tsx` or `.jsx` files; use raw `sed`, `cat`, or similar so JSX syntax is preserved.
2222+- For debugging, use a raw command without `rtk` if the filter hides needed detail.
2323+- Use `apply_patch` for manual edits.
2424+325## Build
426527Use this as the main verification command:
···830rtk npm run build
931```
10321111-The app is a Solid/Vite TypeScript frontend. The build runs `tsc -b && vite build`.
1212-1313-Do not start the Vite dev server from agent sessions. Use the build command for verification.
3333+This is a Solid/Vite TypeScript frontend. The build runs `tsc -b && vite build`.
3434+Do not start the Vite dev server from agent sessions; use the build command for
3535+verification.
14361537## Architecture Map
16381717-Do not start by reading every file. Start from the area you are changing:
3939+Do not start by reading every file. Start from the area you are changing.
18401919-- `src/App.tsx`: app shell, routing, topbar, footer, home page, OAuth callback, not-found page.
4141+- `src/App.tsx`: provider wiring only. Keep this small. It should compose app-wide providers and render `AppRoutes`.
4242+- `src/routes.tsx`: the declarative route table. Repo routes are nested under `/:owner/:repo` and use `RepoLayout`.
4343+- `src/layout.tsx`: global shell and topbar. Preserve the `.untangled-shell` wrapper so app pages keep the intended width and padding. There is intentionally no footer.
4444+- `src/views/home.tsx`: home page and repository jump/recent/own-repo UI.
4545+- `src/views/oauth-callback.tsx`: OAuth callback completion page.
4646+- `src/views/not-found.tsx`: not-found page.
2047- `src/pages/repo.tsx`: barrel exports for repo routes only.
2121-- `src/pages/repo/shared.tsx`: shared repo frame/header/tabs, repo query hook, repo query keys.
4848+- `src/pages/repo/shared.tsx`: repo layout/context, shared repo frame/header/tabs, repo query keys, and `useRepoQuery`.
2249- `src/pages/repo/code.tsx`: repo overview/tree page and blob/file viewer.
2323-- `src/pages/repo/issues.tsx`: issue list, new issue, issue detail.
2424-- `src/pages/repo/pulls.tsx`: pull list, new pull, pull detail, patch/diff rendering calls.
2525-- `src/components/common.tsx`: generic UI primitives such as `Avatar`, `LoadingState`, `StateBadge`, form/button/card style helpers.
2626-- `src/components/repo.tsx`: repo presentation components such as tabs, file rows, README/comment cards, `CodeView`, `DiffView`, branch pills.
2727-- `src/lib/api.ts`: API/client calls and response types.
5050+- `src/pages/repo/code-helpers.ts`: pure code-route helpers such as ref/path resolution, language normalization, delayed loading, and navigation click checks.
5151+- `src/pages/repo/issues.tsx`: issue list, new issue, and issue detail.
5252+- `src/pages/repo/issues-helpers.ts`: issue-specific pure helpers such as comment thread building.
5353+- `src/pages/repo/pulls.tsx`: pull list, new pull, pull detail, and patch/diff rendering calls.
5454+- `src/pages/repo/pulls-helpers.ts`: pull-specific pure helpers such as state filter parsing.
5555+- `src/components/common.tsx`: generic UI primitives such as `Avatar`, `LoadingState`, `StateBadge`, and form/button/card style helpers.
5656+- `src/components/repo.tsx`: repo presentation components such as tabs, file rows, README/comment cards, `CodeView`, `DiffView`, branch pills, and repo skeletons.
5757+- `src/lib/api.ts`: compatibility facade that re-exports domain APIs. Do not add implementation here.
5858+- `src/lib/api/core.ts`: current low-level API implementation and shared private helpers.
5959+- `src/lib/api/constants.ts`: public service URLs and OAuth scope exports.
6060+- `src/lib/api/identity.ts`: auth RPC, identity resolver, actor resolution, avatar resolution.
6161+- `src/lib/api/repos.ts`: repo records, repo metadata, tree/blob/branch/tag/log/language APIs, compare APIs, and related response types.
6262+- `src/lib/api/issues.ts`: issue list/detail/create/comment/state APIs and issue types.
6363+- `src/lib/api/pulls.ts`: pull list/detail/create/comment/status/patch APIs and pull types.
6464+- `src/lib/api/stars.ts`: repo star summary/count/create/delete APIs and star types.
6565+- `src/lib/api/records.ts`: shared record utilities such as AT URI parsing and blob CID extraction.
2866- `src/lib/auth.tsx`: auth provider and OAuth session state.
2967- `src/lib/live-events.tsx`: live websocket event provider/hook.
3030-- `src/lib/repo-utils.ts`: repo URL/path helpers, file type checks, formatting, recent repo storage, language colors, tree sorting.
6868+- `src/lib/repo-utils.ts`: repo URL/path helpers, file type checks, formatting, recent repo storage, language colors, tree sorting, and shared pure repo helpers.
3169- `src/index.css`: global CSS plus explicit utility classes used to replace missing Tailwind arbitrary classes.
32707171+## Repo Route Pattern
7272+7373+Repo pages live under `RepoLayout` in `src/pages/repo/shared.tsx`.
7474+7575+- `RepoLayout` creates the shared repo query once for the `/:owner/:repo` route subtree.
7676+- Child routes must call `useRepoQuery()` instead of creating their own repo query.
7777+- `RepoFrame` owns the shared repo chrome, tab links, star control, recent-repo storage, and live event subscription.
7878+- New repo-route behavior should usually go in a focused `src/pages/repo/*.tsx` file or a small helper beside it, not in `src/App.tsx` or `src/routes.tsx`.
7979+- Keep route files from growing indefinitely. Move pure helpers into `*-helpers.ts` files and reusable display pieces into `src/components/repo.tsx`.
8080+8181+## API Module Pattern
8282+8383+Use domain imports for new code:
8484+8585+```ts
8686+import { getRepoTree } from '../../lib/api/repos';
8787+import { createIssue } from '../../lib/api/issues';
8888+```
8989+9090+The facade `src/lib/api.ts` remains for compatibility with existing imports, but new implementation should go into the relevant domain module or, if it truly must share private internals, into `src/lib/api/core.ts` and be re-exported through the domain module.
9191+9292+Guidelines:
9393+9494+- Do not add new implementation to `src/lib/api.ts`.
9595+- Prefer keeping public types next to the domain module that exposes the API.
9696+- Keep ATProto/PDS resolution rules centralized; repo UI record hydration should resolve the actor/PDS first and call the record endpoint against that PDS.
9797+- Do not use `public.api.bsky.app` for repo `listRecords` or record hydration.
9898+3399## Styling Source Of Truth
3410035101This frontend is intended to match the upstream Tangled app templates in:
···50116- `templates/repo/pulls/fragments/*`
51117- `static/tw.css`
521185353-When matching visuals, compare against those templates before inventing new layout/styling.
119119+When matching visuals, compare against those templates before inventing new
120120+layout/styling.
5412155122## Upstream Comparison Workflow
561235757-For Tangled parity work, use upstream as the contract and compare details before changing local components:
124124+For Tangled parity work, use upstream as the contract and compare details before
125125+changing local components:
5812659127- Start from the matching upstream template in `../tangled-upstream/appview/pages/templates/...`, then check nearby Go/router files when behavior or icon names are data-driven.
60128- For repo chrome, `templates/layouts/repobase.html` is the main reference. Confirm header grouping, action buttons, tab icons, label spacing, font sizes, and vertical padding against that file before patching `src/pages/repo/shared.tsx`.
61129- For code/blob views, compare `templates/repo/index.html` and `templates/repo/blob.html` before changing `src/pages/repo/code.tsx`, `src/components/repo.tsx`, or file-view CSS.
6262-- Treat screenshots as prompts to inspect upstream source, not as the only source of truth. Small differences such as `gap-*`, `py-*`, icon choice, and short-rev styling matter.
6363-- Remove or hide upstream controls that are not implemented locally instead of shipping fake UI. Recent examples: fork action and topbar repo search/jump.
130130+- Treat screenshots as prompts to inspect upstream source, not as the only source of truth.
131131+- Small differences such as `gap-*`, `py-*`, icon choice, and short-rev styling matter.
132132+- Remove or hide upstream controls that are not implemented locally instead of shipping fake UI.
64133- External upstream-only affordances can link to `https://tangled.org`, such as repo stars and `/:owner/:repo/feed.atom`.
6565-- When fetching ATProto records for repo UI, resolve the actor/PDS first and call the record endpoint against that PDS. Do not use `public.api.bsky.app` for repo `listRecords`/record hydration.
6666-- If Vite HMR reports a removed handler or prop after a UI deletion, confirm with `rtk grep` and `rtk npm run build`; stale dev-server modules can survive until the server or page is restarted.
6713468135## Tailwind/CSS Pitfall
691367070-The checked-in `public/static/tw.css` does not include all arbitrary Tailwind classes. Avoid relying on classes such as:
137137+The checked-in `public/static/tw.css` does not include all arbitrary Tailwind
138138+classes. Avoid relying on classes such as:
7113972140- `grid-cols-[...]`
73141- `[overflow-wrap:anywhere]`
74142- `dark:[&_code]:...`
75143- arbitrary safe-area or min-height utilities
761447777-If a class is not present in `public/static/tw.css`, add an explicit `.untangled-*` rule in `src/index.css` instead. Many previous visual bugs were caused by the browser dropping missing arbitrary classes.
145145+If a class is not present in `public/static/tw.css`, add an explicit
146146+`.untangled-*` rule in `src/index.css` instead.
7814779148## Repo UI Notes
80149150150+- Preserve the `.untangled-shell` wrapper in `RootShell`; widening pages changes the app layout.
151151+- Do not add a footer unless explicitly requested.
81152- File/tree ordering should be folders first, then files alphabetically. This is implemented in `sortedTreeEntries` in `src/lib/repo-utils.ts`.
82153- File/blob rendering uses `CodeView` in `src/components/repo.tsx`.
83154- PR diffs use `DiffView`, which parses unified patches into collapsible per-file panels and reuses `CodeView`.
84155- Repo overview and blob pages should resolve `HEAD` to the default branch for user-facing links when possible.
85156- Keep unimplemented upstream features visually inert rather than adding fake behavior.
8686-87157- Repo commit lists should show author avatars like upstream. Upstream maps verified commit author emails to DIDs server-side; the local app can render `Avatar` when the commit author email is already a DID, otherwise use `PlaceholderAvatar`.
88158- The upstream placeholder avatar is a rounded gray background with a centered `user-round` icon. Use `PlaceholderAvatar` from `src/components/common.tsx` instead of a plain empty circle.
89159- Do not show a verified-looking commit badge unless signature validity is actually checked. Use the neutral commit badge/icon for commit hashes.
90160- Repo stars must count backlinks for both `sh.tangled.feed.star:subject.did` and legacy/alternate `sh.tangled.feed.star:subjectDid`, then dedupe hydrated refs.
91161- Star and unstar should be optimistic. Unstar deletes the current user's `sh.tangled.feed.star` record and should update local state without refetching.
92162- While star summary is loading, make the star control unclickable and show the upstream-style `loader-circle` spinner (`LoaderCircle` with `animate-spin` locally).
9393-- Markdown rendering should not enable hard line breaks globally for README-style content; `marked` should use `breaks: false` to avoid mid-line wrapping artifacts.
163163+- Markdown rendering should not enable hard line breaks globally for README-style content; `marked` should use `breaks: false`.
9416495165## Editing Guidance
961669797-- Keep `src/App.tsx` small. New repo-route behavior should usually go into `src/pages/repo/*.tsx`.
167167+- Keep `src/App.tsx` small.
168168+- Keep route declarations in `src/routes.tsx`.
169169+- Keep global shell/topbar work in `src/layout.tsx`.
170170+- Keep top-level non-repo pages in `src/views`.
171171+- Keep repo-route behavior in `src/pages/repo/*.tsx`.
172172+- Keep repo-route pure helpers in nearby `src/pages/repo/*-helpers.ts` files.
98173- Keep generic display components in `src/components/common.tsx`.
99174- Keep repo-specific display components in `src/components/repo.tsx`.
100100-- Keep pure helpers in `src/lib/repo-utils.ts`.
175175+- Keep shared pure repo helpers in `src/lib/repo-utils.ts`.
101176- Do not add large page logic back into `src/App.tsx`.
102102-- Use `apply_patch` for manual edits.
103103-- Do not remove existing behavior while restructuring. Run `rtk npm run build` after meaningful changes.
177177+- Do not remove existing behavior while restructuring.
178178+- Run `rtk npm run build` after meaningful changes.
104179105180## Current Size Guide
106181107107-Approximate current file sizes:
182182+Approximate current file roles:
108183109109-- `src/App.tsx`: small app shell and routing.
110110-- `src/pages/repo/code.tsx`: largest file; split further if code/blob logic grows.
184184+- `src/App.tsx`: tiny provider shell.
185185+- `src/layout.tsx`: global topbar/shell.
186186+- `src/routes.tsx`: route table.
187187+- `src/pages/repo/code.tsx`: largest repo route; split further if code/blob logic grows.
111188- `src/pages/repo/pulls.tsx`: pull routes and patch/diff UI.
112189- `src/pages/repo/issues.tsx`: issue routes.
113113-114114-If a file grows substantially, prefer extracting focused components or helpers rather than continuing to grow the route file.
115115-116116-117117-<!-- headroom:rtk-instructions -->
118118-# RTK (Rust Token Killer) - Token-Optimized Commands
119119-120120-When running shell commands, **always prefix with `rtk`**. This reduces context
121121-usage by 60-90% with zero behavior change. If rtk has no filter for a command,
122122-it passes through unchanged — so it is always safe to use.
123123-124124-## Key Commands
125125-```bash
126126-# Git (59-80% savings)
127127-rtk git status rtk git diff rtk git log
128128-129129-# Files & Search (60-75% savings)
130130-rtk ls <path> rtk read <file> rtk grep <pattern>
131131-rtk find <pattern> rtk diff <file>
132132-133133-# Test (90-99% savings) — shows failures only
134134-rtk pytest tests/ rtk cargo test rtk test <cmd>
135135-136136-# Build & Lint (80-90% savings) — shows errors only
137137-rtk tsc rtk lint rtk cargo build
138138-rtk prettier --check rtk mypy rtk ruff check
139139-140140-# Analysis (70-90% savings)
141141-rtk err <cmd> rtk log <file> rtk json <file>
142142-rtk summary <cmd> rtk deps rtk env
143143-144144-# GitHub (26-87% savings)
145145-rtk gh pr view <n> rtk gh run list rtk gh issue list
146146-147147-# Infrastructure (85% savings)
148148-rtk docker ps rtk kubectl get rtk docker logs <c>
149149-150150-# Package managers (70-90% savings)
151151-rtk pip list rtk pnpm install rtk npm run <script>
152152-```
153153-154154-## Rules
155155-- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`
156156-- Use `rtk rg` for searching, including TSX/JSX files.
157157-- Do not use RTK for reading `.tsx` or `.jsx` files; use raw `sed`, `cat`, or similar so JSX syntax is preserved.
158158-- For debugging, use raw command without rtk prefix.
159159-- `rtk proxy <cmd>` runs command without filtering but tracks usage
160160-<!-- /headroom:rtk-instructions -->
190190+- `src/lib/api/core.ts`: compatibility implementation backend; prefer new domain modules for new API surfaces.