Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (52 loc) · 4.56 KB

AGENTS.md

File metadata and controls

68 lines (52 loc) · 4.56 KB
Raw

Weekly Agent Guide

Project

Weekly is an Astro and Markdown static site for weekly posts.

Deploy surface: pushing main is production. Vercel builds and publishes weekly.tw93.fun automatically on every push; there is no staging.

Repository Map

  • src/pages/posts/ - Chinese posts, one file per issue, named {issue-number}-{Chinese-title}.md.
  • src/pages/en/posts/ - English translations, matched to the Chinese post by the {issue-number}- filename prefix (the slug after the number may differ).
  • src/ - Astro source, shared utilities, and page components.
  • public/ - static assets; public/posts.json is generated by build.js.
  • README.md post list, RECENT.md, and public/posts.json - all generated by build.js; do not hand-edit.
  • scripts/ - maintenance scripts, including image probing and translation helpers.
  • Machine-readable surfaces, all generated at build time from the same posts, never hand-edited:
    • src/agents.ts - issue metadata, Markdown twins (/posts/{n}.md, /en/posts/{n}.md), /index.md, /en/index.md.
    • src/agentGuide.ts - /llms.txt, /llms.md, /api/llms.txt, /posts/llms.txt.
    • src/pages/api/ - read-only JSON API; src/pages/openapi.json.ts describes it; src/pages/feeds/posts.jsonl.ts and src/pages/schemamap.xml.ts are the structured-data feeds.
    • src/aboutMarkdown.ts plus src/data/about.*.md and src/data/faq.ts - single source for /about, /en/about and their .md twins.
    • public/.well-known/ - RFC 9727 API catalog and the Agent Skills index; public/skills/ - published SKILL.md.
    • vercel.json - content types for .md/.jsonl/api-catalog, RFC 8288 Link headers, /api rewrite, ?mode=agent redirect.
  • .github/workflows/build.yml - daily and on-push workflow that runs build.js, commits regenerated indexes, and pings IndexNow. It does not deploy the site; Vercel does.
  • .github/workflows/translate-posts.yml - translates new Chinese posts on push (and manually).

Commands

pnpm install
pnpm dev
pnpm build
pnpm preview
pnpm image:probe
GROK_API_KEY=your_key node scripts/translate_posts.js

pnpm build runs scripts/probe-images.js before the Astro build and pagefind after the build.

Content Rules

  • Frontmatter: date (format YYYY/MM/DD) is required; image is optional. The post title comes from the filename, not frontmatter.
  • Chinese posts: src/pages/posts/{issue-number}-{Chinese-title}.md; English posts live in src/pages/en/posts/ keyed by the same issue-number prefix. Do not mix languages in a single file.
  • The site ships two language surfaces. Before changing any page-level metadata (share/OG title, description, social card), list both the Chinese and English copies plus the share-card fields, and sync all of them; the English site keeping a Chinese share title is the known failure this rule exists for.
  • Preserve the author's voice: do not make colloquial phrasing formal, do not add emoji unless the original has them.
  • Claims in the agent surfaces (llms.txt, /llms.md, /about, JSON-LD, SKILL.md, agent-skills index) must stay checkable against the repo: issue counts come from the post set, the first issue is 2020/11/24, and the site has no write API, no auth and no sandbox. Do not advertise an endpoint, credential flow or MCP surface that does not exist.

Working Rules

  • Do not delete existing posts or rewrite old content unless the task explicitly asks for it.
  • Let build.js regenerate README.md, RECENT.md, and public/posts.json after content changes; do not edit them by hand.
  • Keep generated files under dist/ out of commits.
  • Translation automation writes missing English posts under src/pages/en/posts/; preserve Markdown and frontmatter shape.
  • Prefer small content or component edits with targeted verification.

Verification

  • Site or content changes: run pnpm build. For image-processing, translation, or frontmatter edits, also run pnpm dev and inspect the affected pages yourself; a green build does not mean the page still looks right, and push is production.
  • Image-related changes: run pnpm image:probe or rely on the prebuild step.
  • Translation changes: verify GROK_API_KEY is provided before running scripts/translate_posts.js, then inspect generated English Markdown before committing.
  • Local visual checks: run pnpm dev and inspect the affected page.
  • Documentation-only changes: check links and commands.

GitHub Operations

  • Use gh for issue and PR inspection.
  • Do not post public comments unless the maintainer explicitly asks.
  • Draft public replies in the same language as the thread.