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
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- add-page-sectionSkill
- database-changeSkill
- portfolio-security-checkSkill
- verify-changesSkill
- add-page-sectionSkill
- database-changeSkill
- portfolio-security-checkSkill
- verify-changesSkill
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
- Very specific: line 21
Use Bun (bun.lock is the lockfile).
- Very specific: line 32
Before you finish any code change, run lint, the type check, the tests and the build.
- Very specific: line 59
Keep visible keyboard focus: don't remove outlines without a replacement.
- Very specific: line 75
Every new table: ENABLE ROW LEVEL SECURITY, explicit GRANTs, a public read policy only if the data is public, and an "Admins manage" policy …
- Very specific: line 76
Never use or expose a service-role key in client code or VITE_* variables.
- Distinctive: line 82
Commit to main only in a working state: type check, tests and build pass, and the files you changed lint clean.
- Distinctive: line 83
Never force-push or rewrite pushed history (see the Lovable note above).
- Distinctive: line 84
Write commit messages in the imperative mood ("Add …", "Fix …").
- Very specific: line 89
Read the matching SKILL.md before starting one of these tasks:
≈ “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.
Files
<!-- 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.
| Task | Command |
| Install | bun install |
| Dev server | bun run dev |
| Lint | bun run lint |
| Tests | bun run test |
| Type check | bunx tsc --noEmit |
| Build | bun 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.tsand exposed as queryOptions insrc/data/index.ts; profile lives in the single-rowsite_profiletable (staticsrc/data/profile.tsis 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(layoutadmin.tsx, client-onlybeforeLoadgate →/admin/loginvia un-nestedadmin_.login.tsx); writes go through the browser client so RLShas_role('admin')is the real guard. Migration0005_security_hardening.sqlremoved the old first-sign-up-becomes-admin trigger; admins are granted only by inserting intopublic.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.tsto change what the live site shows; it is changed in the admin UI.
Conventions
- Routing is file-based in
src/routes/(readsrc/routes/README.md). Every public route builds itshead()withseo()fromsrc/lib/seo.ts(title viapageTitle(), plus description, canonical URL, Open Graph and Twitter tags). DefineloaderbeforeheadsoloaderDatais typed. New public pages are also added topublic/sitemap.xml. - Data flow for a public page: server fn in
portfolio.functions.ts→queryOptionsinsrc/data/index.ts→context.queryClient.ensureQueryData(...)in the routeloader→useSuspenseQueryin the component. - Server fns select explicit column lists (never
*) and throw a genericErrormessage, not the raw Supabase error. - Shared types live in
src/data/types.ts. Use the@/import alias forsrc/. - 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). ReusePageandSectionHeaderfromsrc/components/site/primitives.tsx. - Formatting follows
.prettierrc; runbun run formaton files you touched if needed.
Site assistant (src/lib/chat/)
- The assistant panel (
AssistantProviderinsrc/components/site/ChatAssistant.tsx) is opened from the header ("Ask AI", an icon on mobile) and from a prompt on the home page, throughuseAssistant()(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_MODELinassistant.server.ts). One structured-output request per question returns{ reply, suggested_page };suggested_pagemust be one ofASSISTANT_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_KEYis server-only (Lovable Cloud secrets, or.env.locallocally; never.envorVITE_*). Server-only code lives in*.server.tsfiles 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()inprompt.ts, keep it deterministic (for prompt caching), then runbun 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, neverrole="button"on a container, and never nested inside each other. For a clickable card, use a button in the heading whoseafter:absolute after:inset-0overlay covers the card, and lift inner links withrelative z-10(seesrc/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 withtarget="_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 insrc/styles.csshandles therevealutility. - 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.tsandclient.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.tsplugins:@lovable.dev/vite-tanstack-configalready includes them, and adding them again breaks the build.
Security rules
- Every new table:
ENABLE ROW LEVEL SECURITY, explicitGRANTs, a public read policy only if the data is public, and an"Admins manage"policy usingpublic.has_role(auth.uid(), 'admin'). - Never use or expose a service-role key in client code or
VITE_*variables..envholds only the publishable key. - User-supplied URLs must be
https://: validate them withisSafeUrl()from@/lib/utilsin forms and before rendering, add a DB CHECK constraint, and open external links withtarget="_blank" rel="noreferrer". - No
dangerouslySetInnerHTML. Markdown is rendered withreact-markdown. - Security headers (CSP, X-Frame-Options, Permissions-Policy) are set in
src/lib/security-headers.ts, are covered bysrc/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
mainonly 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:
| Skill | Use when |
verify-changes | Before finishing or committing any change |
add-page-section | Adding a new public page or portfolio section |
database-change | Adding or changing a table, column, policy or server fn |
portfolio-security-check | Reviewing auth, RLS, admin or link-handling changes |
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
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.

