unic / unic/ai-developer-hub

Add root README.md with onboarding and env reference

Open Beginner friendly
#52 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation priority:medium
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

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.