Skip to content

AGENTS.md

Latest commit

ย 

History

History
88 lines (64 loc) ยท 3.89 KB

AGENTS.md

File metadata and controls

88 lines (64 loc) ยท 3.89 KB

Ramen API โ€” Agent Guide

How to contribute a ramen shop to this repo. Adding a shop is just editing content files โ€” no build or install is required, and CI runs the checks on every PR. This file follows the cross-agent AGENTS.md convention so it is not tied to a single tool.

Add a ramen shop

This is the main way people contribute. Add one shop end to end.

Inputs to collect (ask if missing โ€” do not guess)

  1. name โ€” shop name (Japanese is fine), e.g. ๅ‰ๆ‘ๅฎถ.
  2. shopId โ€” lowercase slug matching ^[0-9a-z\-]+$, e.g. yoshimuraya. Must be unique (not already in content/shops.json).
  3. photo โ€” path to a real image the user provides. Do not invent one.
  4. author โ€” authorId (^[0-9a-zA-Z\-\_]+$), display name, profile url (^https?://.+). Reuse an existing content/authors/{authorId} if present.
  5. prefecture โ€” optional; see step 4.

Steps

  1. Check the id is free โ€” {shopId} not in content/shops.json and content/shops/{shopId}/ does not exist.

  2. Author โ€” if content/authors/{authorId}/info.json is missing, create it:

    {
  "id": "{authorId}",
  "name": "{name}",
  "url": "https://github.com/{authorId}"
}

  3. Photo โ€” must be under 300KB, EXIF-stripped, longest side ~800px, named {shopId}-001.jpg (-002, โ€ฆ for more). Use the helper (macOS sips + jpegtran):

    mkdir -p content/shops/{shopId}
sh tools/resize.sh /path/to/original.jpg content/shops/{shopId}/{shopId}-001.jpg

    It prints the final pixelHeight/pixelWidth โ€” record them. Off macOS use an equivalent (ImageMagick convert -resize 800x800 -strip, read size with identify -format '%w %h').

  4. Prefecture (optional but encouraged) โ€” the ้ƒฝ้“ๅบœ็œŒ the shop is physically in (must end with ้ƒฝ/้“/ๅบœ/็œŒ). Verify the real location (search the web); do not infer from the name โ€” a "ๆœญๅนŒใƒฉใƒผใƒกใƒณ" shop can be in Kanagawa, a ๅฎถ็ณป shop can be in Tokyo. For a nationwide chain or any shop whose branch you cannot pin down, omit the field entirely rather than recording a guess.

  5. Write content/shops/{shopId}/info.json โ€” field order id, name, prefecture (if known), photos. Do not add a url field (it is generated at runtime).

    {
  "id": "{shopId}",
  "name": "{name}",
  "prefecture": "{prefecture}",
  "photos": [
    {
      "name": "{shopId}-001.jpg",
      "width": 800,
      "height": 600,
      "authorId": "{authorId}"
    }
  ]
}

  6. Register โ€” append "{shopId}" to the end of the shopIds array in content/shops.json.

  7. (Optional) PR โ€” if contributing upstream, create a branch, commit only when asked, and open a PR (e.g. gh pr create) titled add {shopId}.

Validation rules

field rule
id ^[0-9a-z\-]+$
photos[].name ^[0-9a-z\-\.]+\.(jpg|jpeg|png|gif)$
photos[].width / height numbers (the real pixel size)
photos[].authorId ^[0-9a-zA-Z\-\_]+$, must resolve to an author
prefecture optional; if present must end with ้ƒฝ/้“/ๅบœ/็œŒ

Conventions / gotchas

  • Never store a photo url; it is generated by the API at runtime.
  • Keep photos under 300KB, longest side ~800px, EXIF stripped.
  • Omit prefecture when uncertain; never fabricate a location.

Optional: local checks

Not required โ€” CI runs these on every PR. If you want to verify locally (package manager is bun):

bun install            # only needed for local checks
bun run test           # unit + integration tests
bun run validate       # validate all shop/author content