Initialization:

Author: codysj

.claude/agents/db-inspector.md

@@ -0,0 +1,20 @@
+---
+name: db-inspector
+description: Connects to the local dev PostgreSQL database via psql and explains schema and data state in plain English. Read-only — never modifies the database.
+tools:
+  - Bash
+  - Read
+---
+
+You run read-only psql commands against the local dev database (connection string from `.env` or Docker Compose defaults: `postgresql://postgres:postgres@localhost:5432/college_exploration`) and explain what you find.
+
+Permitted commands only:
+- `\dt` — list tables
+- `\d <table>` — describe a table's columns and indexes
+- `SELECT COUNT(*) FROM <table>` — row counts
+- `EXPLAIN SELECT ...` — query plan (no `EXPLAIN ANALYZE` — that executes the query)
+
+Never run: `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, or any DDL.
+Never modify the database.
+
+Report table names, column types, row counts, and index presence in plain English. If the database is not running or the connection fails, report the error and stop.

.claude/agents/explorer.md

@@ -0,0 +1,15 @@
+---
+name: explorer
+description: Investigates the codebase and returns concise summaries of relevant files, symbols, and structure. Use for orientation before editing — never for making changes.
+tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+You investigate the codebase and return concise summaries. Never edit files. Return:
+- Relevant file paths with one-line descriptions
+- Key functions/classes with signatures
+- A 3-sentence synthesis of what you found
+
+No code blocks unless explicitly asked. When nothing relevant is found, say so briefly.

.claude/agents/ranking-tester.md

@@ -0,0 +1,20 @@
+---
+name: ranking-tester
+description: Runs the ranking test suite and reports failures with file:line references and likely root causes. Locked to tests/ranking/ only — does not touch any other tests or files.
+tools:
+  - Bash
+  - Read
+---
+
+You run `cd apps/api && uv run pytest tests/ranking/ -v` and report results.
+
+For each failure, cite:
+1. The file and line number (file:line)
+2. The assertion that failed
+3. Your best guess at the root cause
+
+Rules:
+- Do not edit any files.
+- Do not run tests outside `tests/ranking/`.
+- If `tests/ranking/` does not exist yet, say so and stop.
+- If the command itself fails to run (missing deps, import errors), report the error output verbatim.

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls /mnt/c/Users/Codys/OneDrive/Desktop/Projs/College_Exploration/docs/)"
+    ]
+  }
+}

.claudeignore

@@ -0,0 +1,13 @@
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+.venv/
+*.pyc
+data/raw/*
+*.log
+coverage/
+.pytest_cache/
+pnpm-lock.yaml
+uv.lock

.env.example

@@ -0,0 +1,14 @@
+# Shared
+APP_ENV=development
+
+# Frontend
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+
+# Backend
+API_HOST=127.0.0.1
+API_PORT=8000
+DATABASE_URL=postgresql://college:college@localhost:5432/college_exploration
+REDIS_URL=redis://localhost:6379/0
+
+# External services
+# OPENAI_API_KEY=

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  frontend:
+    name: Frontend placeholder
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/web
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check frontend scaffold
+        shell: bash
+        run: |
+          if [ -f package.json ]; then
+            echo "TODO: replace placeholder with frontend install, lint, and build commands."
+            echo "Example: pnpm install --frozen-lockfile && pnpm lint && pnpm build"
+          else
+            echo "apps/web has no package.json yet; skipping frontend lint/build placeholder."
+          fi
+
+  backend:
+    name: Backend placeholder
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/api
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check backend scaffold
+        shell: bash
+        run: |
+          if [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+            echo "TODO: replace placeholder with backend dependency install and test commands."
+            echo "Example: pytest"
+          else
+            echo "apps/api has no Python project file yet; skipping backend test placeholder."
+          fi

.gitignore

@@ -0,0 +1,42 @@
+# Node / Next.js
+node_modules/
+.next/
+out/
+dist/
+*.tsbuildinfo
+.env*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build / test artifacts
+coverage/
+htmlcov/
+.coverage
+build/
+
+# Environment / secrets
+.env
+.env.local
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Data snapshots (raw sources can be large; keep directory marker only)
+data/raw/*
+!data/raw/.gitkeep

AGENTS.md

@@ -0,0 +1,54 @@
+# Agent Instructions
+
+These instructions apply to Codex and other LLM coding agents working in this repository.
+
+## Coding Standards
+
+- Read `README.md`, `tasks.md`, `docs/architecture.md`, and the docs relevant to the current task before editing.
+- Keep each implementation step small and aligned with the V1/V2/V3 roadmap.
+- Prefer typed contracts and explicit validation over ad hoc objects.
+- Keep SQL out of route handlers when backend code is added; use repository or service modules.
+- Use parameterized SQL only. Never concatenate user input into SQL.
+- Treat missing data as unknown, not as zero, unless zero is semantically correct.
+- Keep application logic deterministic where user decisions depend on ranking, sorting, filtering, or scoring.
+
+## Validation Commands
+
+Real commands will be added as the apps are implemented. Expected future commands:
+
+```powershell
+cd apps/web; pnpm lint; pnpm build
+cd apps/api; pytest
+pnpm exec playwright test
+```
+
+Until those runtimes exist, validate foundation changes with:
+
+```powershell
+Get-ChildItem -Recurse -File
+```
+
+## Documentation Update Rules
+
+- Update `tasks.md` whenever a roadmap item changes status.
+- Update `docs/api-contract.md` in the same change as any endpoint contract.
+- Update `docs/data-dictionary.md` in the same change as schema, seed, or data-source changes.
+- Update `docs/scoring-methodology.md` in the same change as ranking or explanation logic.
+- Update `docs/deployment.md` when infrastructure, environment variables, or deployment steps change.
+- Do not claim measured performance, users, uptime, or deployment status unless those facts have been verified.
+
+## LLM Guardrails
+
+- Do not build V2 or V3 features before the required V1 foundation is stable.
+- Do not invent college facts, data-source freshness, performance numbers, users, or deployment status.
+- Do not present the product as admissions advice, guaranteed ROI, or financial advice.
+- Do not store sensitive student details without clear product boundaries and privacy documentation.
+- Prefer fixtures, seed data, tests, and typed schemas over mock-only demos.
+
+## Ranking and Generated Text
+
+Keep deterministic ranking separate from LLM-generated text.
+
+- Ranking scores, sort order, category scores, confidence, reason codes, and tradeoffs must come from deterministic code and structured data.
+- LLM-generated text may later summarize known deterministic outputs, but it must not create school facts, change scores, decide rankings, or hide missing data.
+- Every ranking logic change must update the scoring methodology docs and use a versioned ranking constant once the ranking engine exists.

CLAUDE.md

@@ -0,0 +1,41 @@
+# College Exploration Platform
+
+Full project spec: docs/SPEC.md (read on demand, not by default)
+Current task tracker: tasks.md (always check before starting work)
+Architecture: docs/architecture.md
+API contract: docs/api-contract.md
+Scoring methodology: docs/scoring-methodology.md
+Data dictionary: docs/data-dictionary.md
+
+## Stack
+- Frontend: Next.js App Router + TypeScript + Tailwind + shadcn/ui (apps/web)
+- Backend: FastAPI + Pydantic + SQLAlchemy (apps/api)
+- DB: PostgreSQL 16 + pgvector (Docker for dev, RDS for prod)
+- Cache: Redis (Docker for dev)
+- Tests: pytest, Vitest + RTL, Playwright
+
+## Commands
+- Web: `cd apps/web && pnpm dev | pnpm test | pnpm lint | pnpm build`
+- API: `cd apps/api && uv run uvicorn app.main:app --reload`
+- API tests: `cd apps/api && uv run pytest`
+- DB: `docker compose up -d postgres redis`
+- Migrations: `cd apps/api && uv run alembic upgrade head`
+- E2E: `pnpm exec playwright test`
+
+## Hard rules (from spec section 3.3)
+- Never build V2 features before V1 is complete and stable
+- Never replace deterministic ranking with LLM output
+- Never invent performance numbers — mark as placeholder if not measured
+- Never use string-concatenated SQL; parameterized only
+- Missing data is never zero unless zero is semantically correct
+- All API responses are typed (Pydantic on backend, generated types on frontend)
+
+## Conventions
+- Repository pattern: SQL stays in repos/, never in route handlers
+- Cache keys include ranking_version and schema_version
+- Every ranking change requires a bumped ranking_version constant
+- New endpoints update docs/api-contract.md in the same commit
+
+## Definition of done (spec 3.4)
+Functional + Technical + Tested + UX-coherent + Documented.
+Don't claim a milestone is done until all five gates pass.