Skip to content

Add root README.md with onboarding and env reference #52

@studert

Description

@studert

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:

  1. 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."

  2. 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.

  3. 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.

  4. 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.

  5. Common commands — copy from CLAUDE.md (pnpm lint, pnpm typecheck, pnpm test, pnpm test:integration, pnpm test:e2e, pnpm build).

  6. Project structure — 8–10 line tree, link to CLAUDE.md for the full version.

  7. 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).

  8. 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.md exists 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

  1. Clone the repo into a fresh directory.
  2. Follow only the README's quick-start steps.
  3. Confirm pnpm dev starts successfully and /login renders without errors.
  4. View the README on GitHub — confirm formatting and links work.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpriority:mediumImportant, not urgent

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions