Skip to content

Commit 26ac2ef

Browse files
BjornMelinBjornMelin
committed
docs: add repository docs and scripts
1 parent 5d15dd7 commit 26ac2ef

6 files changed

Lines changed: 220 additions & 0 deletions

File tree

‎.env.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Database (Neon)
2+
DATABASE_URL=
3+
4+
# Upstash
5+
UPSTASH_REDIS_REST_URL=
6+
UPSTASH_REDIS_REST_TOKEN=
7+
UPSTASH_VECTOR_REST_URL=
8+
UPSTASH_VECTOR_REST_TOKEN=
9+
QSTASH_TOKEN=
10+
11+
# Vercel AI Gateway
12+
AI_GATEWAY_API_KEY=
13+
AI_GATEWAY_BASE_URL=https://ai-gateway.vercel.sh/v1

‎AGENTS.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# AGENTS.md
2+
3+
This repo is optimized for agent-driven development (Codex + local automation).
4+
5+
## Non-negotiables
6+
7+
- **Bun only** for installs and scripts.
8+
- **Next.js App Router** patterns only.
9+
- **No manual memoization** (`useMemo`, `useCallback`).
10+
- **Strict TypeScript** (no `any`).
11+
- **Docs required** for exported APIs (TSDoc syntax enforced).
12+
13+
## Core commands
14+
15+
```bash
16+
bun install # Install dependencies
17+
bun run dev # Start development server
18+
bun run build # Build for production
19+
bun run format # Format code with Biome
20+
bun run lint # Run Biome and ESLint
21+
bun run typecheck # Run TypeScript compiler checks
22+
bun run test # Run tests with Vitest
23+
bun run ci # Run format/lint/typecheck/test/build
24+
bun run db:generate # Generate database migrations
25+
bun run db:migrate # Apply database migrations
26+
bun run db:studio # Open Drizzle Studio (requires DATABASE_URL)
27+
bun run fetch:models # Update AI model catalog (requires AI_GATEWAY_API_KEY)
28+
```
29+
30+
## Formatting & linting
31+
32+
- Biome is the primary formatter/linter.
33+
- ESLint is used for:
34+
- TSDoc syntax enforcement (`tsdoc/syntax`)
35+
- JSDoc policy on exported APIs (warn-level for iteration speed)
36+
37+
## Drizzle + database
38+
39+
- `drizzle.config.ts` reads `DATABASE_URL` at runtime; `bun run db:*` commands will fail fast if it's missing.
40+
- Schema lives in `src/db/schema.ts` and migrations are generated into `src/db/migrations`.
41+
42+
## Database
43+
44+
- Drizzle schema: `src/db/schema.ts`
45+
- Migrations: `src/db/migrations`
46+
47+
## AI Gateway
48+
49+
- Prefer `ai` package `gateway(...)` usage for model routing.
50+
- OpenAI-compatible base URL is `https://ai-gateway.vercel.sh/v1`.
51+
- `bun run fetch:models` writes a model catalog JSON (default: `docs/ai-gateway-models.json`).
52+
53+
## Definition of done (for any PR)
54+
55+
- `bun run format` clean
56+
- `bun run lint` clean
57+
- `bun run typecheck` clean
58+
- `bun run test` clean
59+
- `bun run build` clean
60+
- No console spam in production paths
61+
- Public/exported APIs have valid TSDoc
62+
- Any env vars added are reflected in `.env.example`

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
This repository uses Release Please and Conventional Commits.

‎CITATION.cff‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
cff-version: 1.2.0
2+
title: ai-agent-builder
3+
message: >-
4+
If you use this software, please cite it using the metadata in this file.
5+
type: software
6+
authors:
7+
- name: Bjorn Melin

‎README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# AI Agent Builder
2+
3+
![Bun](https://img.shields.io/badge/Bun-1.x-000000?logo=bun&logoColor=white)
4+
![Next.js](https://img.shields.io/badge/Next.js-16-000000?logo=next.js&logoColor=white)
5+
![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=000000)
6+
![Tailwind](https://img.shields.io/badge/TailwindCSS-4-06B6D4?logo=tailwindcss&logoColor=white)
7+
![Vercel](https://img.shields.io/badge/Deploy-Vercel-000000?logo=vercel&logoColor=white)
8+
![Postgres](https://img.shields.io/badge/DB-Neon_Postgres-4169E1?logo=postgresql&logoColor=white)
9+
![Redis](https://img.shields.io/badge/Cache-Upstash-00E9A3?logo=redis&logoColor=white)
10+
11+
A single-user, production-focused system for turning rough product ideas
12+
(pitch decks, docs, spreadsheets, notes) into a complete, implementation-ready
13+
spec set: market research, competitive analysis, differentiation, PRD, ADRs,
14+
architecture, and Codex-ready implementation prompts.
15+
16+
## What it does
17+
18+
- Ingests source material: PDFs, slides, docs, markdown, spreadsheets.
19+
- Runs deep research and validation:
20+
- competitors, positioning, pricing signals, go-to-market constraints
21+
- feature gaps, differentiation opportunities, risk analysis
22+
- Produces formal, versioned outputs:
23+
- PRD, architecture, ADRs, roadmap, build plan
24+
- Codex prompts structured for end-to-end production implementation
25+
- Keeps an iterative project workspace so you can upload more material and
26+
re-run or refine outputs over time.
27+
28+
## High-level architecture
29+
30+
```mermaid
31+
flowchart LR
32+
A[Uploads / Notes] --> B[Ingestion + Index]
33+
B --> C[Research Agents]
34+
C --> D[Gap + Differentiation]
35+
D --> E[PRD + ADR + Architecture]
36+
E --> F[Codex Implementation Prompts]
37+
F --> G[Export + Versioned Artifacts]
38+
```
39+
40+
## Tech stack
41+
42+
- Runtime + tooling: Bun
43+
- Web: Next.js 16 (App Router), React 19
44+
- Styling/UI: TailwindCSS v4, shadcn/ui, Lucide
45+
- AI: Vercel AI SDK v6 + AI Gateway
46+
- DB: Neon Postgres + Drizzle ORM
47+
- Infra helpers: Upstash (Redis, QStash, Vector)
48+
- Quality: Biome (format/lint) + ESLint (TSDoc/JSDoc enforcement) + Vitest
49+
- Typing/Schema: Zod v4
50+
- Releases: Release Please (semver via Conventional Commits)
51+
52+
## Local development
53+
54+
### Prerequisites
55+
56+
- Bun v1.2+ (uses `bun.lock`)
57+
- A Neon database URL in `DATABASE_URL`
58+
- Upstash credentials (Redis/Vector/QStash)
59+
- Vercel AI Gateway API key (`AI_GATEWAY_API_KEY`)
60+
61+
### Setup
62+
63+
```bash
64+
cp .env.example .env.local
65+
bun install
66+
bun run db:generate
67+
bun run db:migrate
68+
bun run dev
69+
```
70+
71+
## Fetch AI Gateway model catalog
72+
73+
The AI Gateway exposes an OpenAI-compatible models endpoint:
74+
`GET https://ai-gateway.vercel.sh/v1/models`
75+
76+
```bash
77+
AI_GATEWAY_API_KEY=... bun run fetch:models
78+
```
79+
80+
## CI and quality gates
81+
82+
Run the same checks as CI:
83+
84+
```bash
85+
bun run format
86+
bun run lint
87+
bun run typecheck
88+
bun run test
89+
bun run build
90+
```
91+
92+
## Releases and versioning
93+
94+
This repo uses Release Please and Conventional Commits.
95+
96+
While `version < 1.0.0`, breaking changes bump **minor** and features bump
97+
**patch** (to avoid major releases during active development).
98+
99+
## How to cite
100+
101+
This repo includes a `CITATION.cff`. GitHub will surface a “Cite this repository”
102+
entry when the file is present.
103+
104+
## Security
105+
106+
- CodeQL and OpenSSF Scorecard run in GitHub Actions.
107+
- Dependency Review runs on PRs.
108+
- Dependabot is configured for Bun lockfiles (`bun.lock`).

‎scripts/fetch-models.sh‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
# Fetches the AI Gateway model catalog into a JSON file.
5+
# AI Gateway OpenAI-compatible base URL: https://ai-gateway.vercel.sh/v1
6+
# Models endpoint: https://ai-gateway.vercel.sh/v1/models
7+
8+
BASE_URL="${AI_GATEWAY_BASE_URL:-https://ai-gateway.vercel.sh/v1}"
9+
OUT_FILE="${1:-docs/ai-gateway-models.json}"
10+
11+
if [[ -z "${AI_GATEWAY_API_KEY:-}" ]]; then
12+
echo "Error: AI_GATEWAY_API_KEY is required." >&2
13+
echo "Create one in the Vercel Dashboard → AI Gateway." >&2
14+
exit 1
15+
fi
16+
17+
mkdir -p "$(dirname "$OUT_FILE")"
18+
19+
curl -sS \
20+
-H "Authorization: Bearer ${AI_GATEWAY_API_KEY}" \
21+
-H "Accept: application/json" \
22+
"${BASE_URL}/models" \
23+
> "${OUT_FILE}"
24+
25+
echo "Wrote ${OUT_FILE}"

0 commit comments

Comments
 (0)