| name | codebase-map |
| description | Orient in this repo: which file to edit for a change, how a change ripples across the stack, and how to search the code. Use at the start of a task in an unfamiliar area, or before a cross-cutting change. |
Codebase Map
One Bun + Turborepo monorepo: two deployable apps over shared packages. Imports use @api/hono, @packages/*, and the @/ alias, never deep relative paths.
.generated/ # repo-root home for build-time generated assets (gitignored)
api/hono/ # backend (Hono): routers, middlewares, the AppType export
web/next/ # frontend (Next.js App Router): app/, components/, lib/, content/
packages/auth/ # Better Auth instance
packages/db/ # Drizzle schema + client
packages/env/ # type-safe env, one validated entry per consumer
packages/config/ # TS base, tsdown factory, and site.ts (brand identity)
packages/scripts/ # build-only bun tooling (e.g. generate-env, the tldts host breakdown per consumer); never bundled
packages/cli/ # the zerostarter scaffolding CLI (canonical repo only; init strips it)
Read AGENTS.md first for the rules; curl "$(bunx portless get zerostarter)/llms-full.txt" dumps the whole codebase as one context file.
Where to edit for X
| Goal | Edit here | Then |
|---|
| Add/change an API route | api/hono/src/routers/<name>.ts → export from routers/index.ts → mount in src/index.ts .route() chain | api-endpoint skill |
| Change the database schema | packages/db/src/schema/<name>.ts → export from schema/index.ts | db-migration skill |
| Add/change a page | web/next/src/app/, route groups: (marketing) public, (protected) dashboard, (console) admin, (content) docs+blog | - |
| Add/customize a UI component | web/next/src/components/: ui/ is generated shadcn, don't hand-edit | design, shadcn-sync skills |
| Call the API from the web app | web/next/src/lib/api/client.ts (apiClient, unwrap) | - |
| Rebrand (name, description, socials) | packages/config/src/site.ts, one file | - |
| Add or read an env var | packages/env/src/{api-hono,auth,db,web-next}.ts; read via @packages/env/*, never process.env | - |
| Configure auth (providers, plugins) | packages/auth/src/index.ts | - |
| Gate by role | web/next/src/lib/auth/console.ts gates the web admin console; the API's middlewares/auth.ts checks the session only (401), not role | - |
| Change the error/response shape | api/hono/src/lib/error.ts (the { error: { code, message } } handler) | - |
| Change docs structure/sidebar | web/next/docs.config.ts, single source; meta.json is generated | - |
Trace a feature across the stack
Types flow downhill, so a change ripples predictably:
packages/db/src/schema → api/hono/src/routers → api/hono/src/index.ts (AppType) → web/next/src/lib/api/client.ts → app / components
Add a field end to end: edit and migrate the schema, then select/return it in the router. Every apiClient call site is retyped automatically and the compiler becomes your worklist of what still must change.
Entry points (read these first)
api/hono/src/index.ts, the .route() chain and export type AppType, the whole API shape in one file.web/next/src/app/layout.tsx, the web root.packages/config/src/site.ts, brand identity and injectable content.
Fast find
rg -n "\.route\(" api/hono/src/index.ts
rg -n "export const \w+Router" api/hono/src/routers
ls packages/db/src/schema
rg -n "apiClient\." web/next/src
rg -n "SOME_ENV_VAR" packages/env
ls .agents/skills
Then
Load the task skill (the table's right column); dev runs/restarts the stack, and concept docs live under /docs.
