Add root README.md with onboarding and env reference
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
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
lsat repo root shows noREADME.md.- The GitHub repo page therefore renders the file list with no description.
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.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.mdfor 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 devPlus 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. - All quick-start commands are valid and produce a running dev server on a fresh clone.
- Env-var table matches
.env.local.example(or links to it). - Links to
CLAUDE.md,docs/, and any feature-spec folder are present. - Markdown lint clean.
Verification
- Clone the repo into a fresh directory.
- Follow only the README's quick-start steps.
- Confirm
pnpm devstarts successfully and/loginrenders without errors. - View the README on GitHub — confirm formatting and links work.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading CLAUDE.md, .env.local.example, package.json, and the docs and feature-spec folders to gather the canonical commands, variables, links, and license information. Follow the listed quick-start commands and verify that pnpm dev starts and /login renders. Done means a scannable root README.md under about 150 lines with valid links, matching environment documentation, and clean Markdown lint.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- next.js, playwright, tailwindcss
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100