agentleFS
tapiotorstitapiotorsti/torsti-tapiola-website/AGENTS.md

torsti-tapiola-website

AGENTS.md0 starsChanged 3 days agoMITView on GitHub

Personal portfolio site: TanStack Start (React 19, SSR) + Supabase (via Lovable Cloud) + Tailwind CSS 4 + shadcn/ui. This file is the single source of truth for AI coding agents; CLAUDE.md, GEMINI.md and .github/copilot-instructions.md only point here. Use Bun (bun.lock is the lockfile); npm works too. Before you finish any code change, run lint, the type check, the tests and the build. See .agents/skills/verify-changes/SKILL.md. Existing code has many Prettier lint errors (a known baseline), so lint the files you…

  • Reads credentials

The file

We split this AGENTS.md into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Use Bun (bun.lock is the lockfile).

    line 21
  2. Very specific:

    Before you finish any code change, run lint, the type check, the tests and the build.

    line 32
  3. Very specific:

    Keep visible keyboard focus: don't remove outlines without a replacement.

    line 59
  4. Very specific:

    Every new table: ENABLE ROW LEVEL SECURITY, explicit GRANTs, a public read policy only if the data is public, and an "Admins manage" policy …

    line 75
  5. Very specific:

    Never use or expose a service-role key in client code or VITE_* variables.

    line 76
  6. Distinctive:

    Commit to main only in a working state: type check, tests and build pass, and the files you changed lint clean.

    line 82
  7. Distinctive:

    Never force-push or rewrite pushed history (see the Lovable note above).

    line 83
  8. Distinctive:

    Write commit messages in the imperative mood ("Add …", "Fix …").

    line 84
  9. Very specific:

    Read the matching SKILL.md before starting one of these tasks:

    line 89

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- LOVABLE:BEGIN -->

[!IMPORTANT] This project is connected to Lovable. Avoid rewriting published git history — force pushing, or rebasing/amending/squashing commits that are already pushed — as it rewrites history on Lovable's side and the user will likely lose their project history.

Commits you push to the connected branch sync back to Lovable and show up in the editor, so keep the branch in a working state.

<!-- LOVABLE:END -->

Agent guide

Personal portfolio site: TanStack Start (React 19, SSR) + Supabase (via Lovable Cloud) + Tailwind CSS 4 + shadcn/ui. This file is the single source of truth for AI coding agents; CLAUDE.md, GEMINI.md and .github/copilot-instructions.md only point here.

Commands

Use Bun (bun.lock is the lockfile); npm works too.

TaskCommand
Installbun install
Dev serverbun run dev
Lintbun run lint
Testsbun run test
Type checkbunx tsc --noEmit
Buildbun run build

Before you finish any code change, run lint, the type check, the tests and the build. See .agents/skills/verify-changes/SKILL.md. Existing code has many Prettier lint errors (a known baseline), so lint the files you changed (bunx eslint <files>) and keep those clean. Do not reformat the whole repo in an unrelated change.

Project rules

  • Projects, experience and skills live in Cloud tables, read via public server fns in src/data/portfolio.functions.ts and exposed as queryOptions in src/data/index.ts; profile lives in the single-row site_profile table (static src/data/profile.ts is only a fallback). Writes are admin-only (has_role) so signed-up visitors can't edit content.
  • Each portfolio section is its own route with its own head(); shared header/footer wrap <Outlet /> in __root.tsx.
  • Admin lives at /admin (layout admin.tsx, client-only beforeLoad gate → /admin/login via un-nested admin_.login.tsx); writes go through the browser client so RLS has_role('admin') is the real guard. Migration 0005_security_hardening.sql removed the old first-sign-up-becomes-admin trigger; admins are granted only by inserting into public.user_roles. Public sign-up is off.
  • Site content (projects, experience, skills, profile text) is data, not code. Do not hard-code content into components or edit src/data/profile.ts to change what the live site shows; it is changed in the admin UI.

Conventions

  • Routing is file-based in src/routes/ (read src/routes/README.md). Every public route builds its head() with seo() from src/lib/seo.ts (title via pageTitle(), plus description, canonical URL, Open Graph and Twitter tags). Define loader before head so loaderData is typed. New public pages are also added to public/sitemap.xml.
  • Data flow for a public page: server fn in portfolio.functions.ts → queryOptions in src/data/index.ts → context.queryClient.ensureQueryData(...) in the route loader → useSuspenseQuery in the component.
  • Server fns select explicit column lists (never *) and throw a generic Error message, not the raw Supabase error.
  • Shared types live in src/data/types.ts. Use the @/ import alias for src/.
  • Styling: Tailwind utility classes and the design tokens in src/styles.css. Keep the look editorial and minimal: 1px borders, monospace for dates, tags and indices, one accent colour (text-primary). Reuse Page and SectionHeader from src/components/site/primitives.tsx.
  • Formatting follows .prettierrc; run bun run format on files you touched if needed.

Site assistant (src/lib/chat/)

  • The assistant panel (AssistantProvider in src/components/site/ChatAssistant.tsx) is opened from the header ("Ask AI", an icon on mobile) and from a prompt on the home page, through useAssistant() (assistant-context.ts). Don't add a floating button: it covers content and clashes with the editorial layout. It answers questions about the site owner from the public site content only, using Claude Haiku 5.5 (ASSISTANT_MODEL in assistant.server.ts). One structured-output request per question returns { reply, suggested_page }; suggested_page must be one of ASSISTANT_PAGES.
  • Privacy: conversations live only in the widget's memory. Never store, log or send them anywhere except the Anthropic API call. Rate limiting stores only an hourly HMAC of the IP (0009_chat_rate_limit.sql).
  • Security: ANTHROPIC_API_KEY is server-only (Lovable Cloud secrets, or .env.local locally; never .env or VITE_*). Server-only code lives in *.server.ts files that are imported dynamically from the server function. Model output is rendered as plain text. The handler fails closed when the rate limit can't be checked.
  • Prompt changes: edit buildSystemPrompt() in prompt.ts, keep it deterministic (for prompt caching), then run bun scripts/eval-assistant.ts, which needs a key, and check that all cases still pass.

Accessibility (WCAG 2.2 AA)

  • Interactive things are real <button>/<a> elements, never role="button" on a container, and never nested inside each other. For a clickable card, use a button in the heading whose after:absolute after:inset-0 overlay covers the card, and lift inner links with relative z-10 (see src/routes/projects.tsx).
  • Keep visible keyboard focus: don't remove outlines without a replacement. The focus colour is --ring (primary purple). Don't change it to the gold accent, which has too little contrast.
  • Decorative numbers and icons get aria-hidden="true". Links with target="_blank" include <NewTabHint />.
  • Public pages render inside <Page> (<main id="main">), which is the target of the "Skip to content" link.
  • Animations must respect prefers-reduced-motion; the global rule in src/styles.css handles the reveal utility.
  • Text colours from the theme pass 4.5:1. Check the contrast if you introduce new colour pairs.

Do not edit by hand

  • src/routeTree.gen.ts: generated by the TanStack router plugin.
  • src/integrations/supabase/types.ts and client.ts: generated by Lovable Cloud.
  • src/components/ui/*: shadcn/ui components. Add new ones with the shadcn CLI, and wrap rather than fork.
  • drizzle/schema.ts, drizzle/migrations/meta/*: generated.
  • Migrations already in drizzle/migrations/: they are applied. Add a new one instead of editing an old one.
  • .lovable/: Lovable's own files.
  • vite.config.ts plugins: @lovable.dev/vite-tanstack-config already includes them, and adding them again breaks the build.

Security rules

  • Every new table: ENABLE ROW LEVEL SECURITY, explicit GRANTs, a public read policy only if the data is public, and an "Admins manage" policy using public.has_role(auth.uid(), 'admin').
  • Never use or expose a service-role key in client code or VITE_* variables. .env holds only the publishable key.
  • User-supplied URLs must be https://: validate them with isSafeUrl() from @/lib/utils in forms and before rendering, add a DB CHECK constraint, and open external links with target="_blank" rel="noreferrer".
  • No dangerouslySetInnerHTML. Markdown is rendered with react-markdown.
  • Security headers (CSP, X-Frame-Options, Permissions-Policy) are set in src/lib/security-headers.ts, are covered by src/test/security-headers.test.ts, and are skipped in dev and the Lovable preview. If you add an external script, style, font, image or API origin, add it to the CSP in the same change, or production will block it.

Git

  • Commit to main only in a working state: type check, tests and build pass, and the files you changed lint clean.
  • Never force-push or rewrite pushed history (see the Lovable note above).
  • Write commit messages in the imperative mood ("Add …", "Fix …").

Skills

Step-by-step guides in the open Agent Skills format live in .agents/skills/. Read the matching SKILL.md before starting one of these tasks:

SkillUse when
verify-changesBefore finishing or committing any change
add-page-sectionAdding a new public page or portfolio section
database-changeAdding or changing a table, column, policy or server fn
portfolio-security-checkReviewing auth, RLS, admin or link-handling changes

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.