Problem
The repo has no README.md at the root. New contributors (human or agent) land on the GitHub repo page and see no overview, no setup steps, no env reference, and no link to CLAUDE.md or feature specs. CLAUDE.md is comprehensive but is keyed to AI assistants rather than first-time human contributors, and it isn't displayed on the repo home.
Evidence
ls at repo root shows no README.md.
- The GitHub repo page therefore renders the file list with no description.
CLAUDE.md exists with stack/commands/conventions but is large and AI-targeted.
.env.local.example exists but is not linked from anywhere.
Proposed approach
Create a concise README.md at the repo root with these sections:
-
About — 2 sentences: "AI Developer Hub is an internal app for tracking AI tool budgets, GitHub Copilot usage, Claude API costs, license assignments and invoices at Unic."
-
Tech stack — single-paragraph or bullet list (Next.js 15, Drizzle/Neon, NextAuth, shadcn/ui, Tailwind v4, Vitest, Playwright). Link to CLAUDE.md for the canonical list.
-
Quick start — 5 commands or fewer:
pnpm install
cp .env.local.example .env.local # then fill in secrets
pnpm db:push # apply schema to dev DB
pnpm db:seed # creates initial admin
pnpm dev
Plus a one-line note on the seeded admin credentials and where they're documented.
-
Environment variables — table with columns Name | Required | Purpose, generated from / kept in sync with .env.local.example. Link to the env-validator module once issue #ENV_VALIDATOR_ISSUE lands.
-
Common commands — copy from CLAUDE.md (pnpm lint, pnpm typecheck, pnpm test, pnpm test:integration, pnpm test:e2e, pnpm build).
-
Project structure — 8–10 line tree, link to CLAUDE.md for the full version.
-
Contributing — branch naming convention, conventional-commits link, mention CI requirements (once #CI_ISSUE lands), link to the speckit workflow if used (speckit.specify, speckit.plan, speckit.tasks).
-
License — match whatever the package.json field says, or omit if private.
Keep it under ~150 lines. The point is to be scannable, not exhaustive.
Acceptance criteria
Verification
- Clone the repo into a fresh directory.
- Follow only the README's quick-start steps.
- Confirm
pnpm dev starts successfully and /login renders without errors.
- View the README on GitHub — confirm formatting and links work.
Problem
The repo has no
README.mdat the root. New contributors (human or agent) land on the GitHub repo page and see no overview, no setup steps, no env reference, and no link toCLAUDE.mdor feature specs.CLAUDE.mdis comprehensive but is keyed to AI assistants rather than first-time human contributors, and it isn't displayed on the repo home.Evidence
lsat repo root shows noREADME.md.CLAUDE.mdexists with stack/commands/conventions but is large and AI-targeted..env.local.exampleexists but is not linked from anywhere.Proposed approach
Create a concise
README.mdat the repo root with these sections:About — 2 sentences: "AI Developer Hub is an internal app for tracking AI tool budgets, GitHub Copilot usage, Claude API costs, license assignments and invoices at Unic."
Tech stack — single-paragraph or bullet list (Next.js 15, Drizzle/Neon, NextAuth, shadcn/ui, Tailwind v4, Vitest, Playwright). Link to
CLAUDE.mdfor the canonical list.Quick start — 5 commands or fewer:
Plus a one-line note on the seeded admin credentials and where they're documented.
Environment variables — table with columns
Name | Required | Purpose, generated from / kept in sync with.env.local.example. Link to the env-validator module once issue #ENV_VALIDATOR_ISSUE lands.Common commands — copy from
CLAUDE.md(pnpm lint,pnpm typecheck,pnpm test,pnpm test:integration,pnpm test:e2e,pnpm build).Project structure — 8–10 line tree, link to
CLAUDE.mdfor the full version.Contributing — branch naming convention, conventional-commits link, mention CI requirements (once #CI_ISSUE lands), link to the speckit workflow if used (
speckit.specify,speckit.plan,speckit.tasks).License — match whatever the package.json field says, or omit if private.
Keep it under ~150 lines. The point is to be scannable, not exhaustive.
Acceptance criteria
README.mdexists at repo root..env.local.example(or links to it).CLAUDE.md,docs/, and any feature-spec folder are present.Verification
pnpm devstarts successfully and/loginrenders without errors.