Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (101 loc) · 8.09 KB

AGENTS.md

File metadata and controls

146 lines (101 loc) · 8.09 KB
Raw

DOX framework

  • DOX is a high-performance AGENTS.md hierarchy installed here.
  • The agent must follow DOX instructions across any edits.

Core Contract

  • AGENTS.md files are binding work contracts for their subtrees.
  • Work products, source, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it.

Read Before Editing

  1. Read the root AGENTS.md.
  2. Identify every file or folder you expect to touch.
  3. Walk from the repository root to each target path.
  4. Read every AGENTS.md found along each route.
  5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there.
  6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules.
  7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX.

Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.

Update After Editing

Every meaningful change requires a DOX pass before the task is done. Update the closest owning AGENTS.md when a change affects:

  • purpose, scope, ownership, or responsibilities
  • durable structure, contracts, workflows, or operating rules
  • required inputs, outputs, permissions, constraints, side effects, or artifacts
  • user preferences about behavior, communication, process, organization, or quality
  • AGENTS.md creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately.

Hierarchy

  • Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index.
  • Child AGENTS.md files own domain-specific instructions and their own Child DOX Index.
  • Each parent explains what its direct children cover and what stays owned by the parent.
  • The closer a doc is to the work, the more specific and practical it must be.

Child Doc Shape

  • Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards.
  • Work Guidance must reflect current project standards or user instructions; leave empty if none exist yet.
  • Verification must reflect an existing check; leave empty until one exists.

Default section order: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.

Style

  • Keep docs concise, current, and operational.
  • Document stable contracts, not diary entries.
  • Put broad rules in parent docs and concrete details in child docs.
  • Prefer direct bullets with explicit names.
  • Do not duplicate rules across files unless each scope needs a local version.
  • Delete stale notes instead of explaining history.

Closeout

  1. Re-check changed paths against the DOX chain.
  2. Update nearest owning docs and any affected parents or children.
  3. Refresh every affected Child DOX Index.
  4. Remove stale or contradictory text.
  5. Run existing verification when relevant.
  6. Report any docs intentionally left unchanged and why.

Project: IBspace

SaaS for IB Diploma students. Next.js 16 App Router + Supabase (cloud) + Vercel AI Gateway, deployed on Vercel. Flagship live feature: TOK Exhibition helper. Also live: Notes, CAS. Stubs: Extended Essay (EE), TOK Essay.

IMPORTANT!

Follow YAGNI principles, use one-liner solutions. do NOT end git commit messages with: Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com!! Important!!

Stack & Critical Constraints

  • Next.js 16 (App Router, Turbopack). NOT 13/14/15 — breaking changes apply. Before writing framework code, consult node_modules/next/dist/docs/ and heed dev-server deprecation warnings.
    • Middleware is proxy.ts at repo root; the exported function MUST be named proxy (not middleware). The runtime config option is NOT available in proxy files.
    • useSearchParams() must be wrapped in <Suspense> for static generation.
  • React Server Components by default; "use client" only where interactivity requires it.
  • TypeScript strict. @/* path alias maps to repo root (e.g. @/lib/supabase-server).

Design System (project-wide UI law)

Brutalist Pastel theme. Tailwind only — no component libraries. No shadows (except the deliberate card-bump offset), no gradients, no blur, no pill shapes. Reuse the CSS-var tokens and @utility classes defined in app/globals.css — do not reinvent them. Full token + utility catalog lives in app/AGENTS.md. Font: system-ui stack, no Google Fonts.

Commands

  • npm run dev — dev server on :3000 (Turbopack)
  • npm run build — production build (tsc + page generation)
  • npm run start — serve production build
  • Typecheck only: node node_modules/typescript/bin/tsc --noEmit
  • opencode.json: opencode build (tsc+build), opencode check (tsc), opencode commit
  • Background dev: nohup npm run dev > /tmp/dev.log 2>&1 &; kill with kill $(lsof -ti:3000)

Available CLIs

  • Vercel: vercel <cmd> (global alias). Auto-deploys on push to main. Project vsht/ibspace. Env: vercel env add <KEY> production; pull: vc env pull .env.local --environment production.
  • Supabase CLI: not installed. Schema edits go through the Dashboard SQL Editor — see supabase/AGENTS.md.
  • Supabase MCP: supabase-mcp (opencode.json) — SQL, migration apply, TS type gen, table listing. Needs SUPABASE_SERVICE_ROLE_KEY.
  • Supabase Management API: base https://api.supabase.com/v1/projects/pjjupictmrlpxbvhcgxf with PAT — auth provider config (Google OAuth, SMTP).
  • GitHub: gh.

Request Flow

browser → proxy.ts (auth gate) → app/ route → Supabase / AI API

proxy.ts protects /dashboard/**, /profile/**, and /notes/** (redirects unauthenticated → /login) and redirects authenticated users away from /login. /auth/** is exempt.

Environment Variables

Variable Purpose
NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY Supabase client config
SUPABASE_SERVICE_ROLE_KEY Server-only — account deletion, MCP. Never expose to client.
VERCEL_OIDC_TOKEN AI Gateway auth. Pulled via vc env pull. Replaces any GEMINI_API_KEY.
AI_GATEWAY_API_KEY Same value as VERCEL_OIDC_TOKEN (set locally)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET Google OAuth direct flow (server-only)
NEXT_PUBLIC_SITE_URL Canonical base URL for OAuth redirects
PADDLE_API_KEY / PADDLE_WEBHOOK_SECRET / NEXT_PUBLIC_PADDLE_CLIENT_TOKEN / NEXT_PUBLIC_PADDLE_STUDENT_PRICE_ID Paddle payments (scaffold, not yet implemented)

Deployment

Vercel; GitHub push to main → auto build. Pre-deploy: npm run build must pass with zero TS errors; run pending Supabase migrations in the SQL Editor; verify /api/health returns {"status":"ok"}. Migration workflow in supabase/AGENTS.md.

Reference Docs (repo root, not DOX nodes)

  • TODO.md — pending-work backlog. Read before significant work; delete items when done.
  • FEATURES.md — catalog of built features. Append when finishing significant features.
  • PRODUCT.md, DESIGN.md, STYLE.md, NOTES-SPEC.md, README.md, HUMANS.md — product/design references.
  • graphify knowledge graph at graphify-out/; run graphify update . after code changes.

User Preferences

  • Caveman mode: communicate with the user using /caveman (full intensity); commits use /caveman-commit format. Do not revert to normal mode unless the user says "stop caveman" / "normal mode". DOX docs themselves are written in clear operational English for precision.

Child DOX Index

  • app/AGENTS.md — Next.js App Router: routes, pages, route handlers, RSC/client rules, design-system token + utility catalog.
  • components/AGENTS.md — shared cross-route UI components and their server/client split.
  • lib/AGENTS.md — Supabase clients (server/browser), AI SDK wrapper, rate limiter, toast, prompts, cookie consent.
  • supabase/AGENTS.md — database schema, RLS, and the manual SQL-Editor migration workflow.