paper-reading

Imported from ZeroYuHuang/paper-reading (AGENTS.md). Install upstream with npx skills add ZeroYuHuang/paper-reading. Copyright stays with the author.

AGENTS.md

Purpose

This repository is primarily a reading-notes repo with one substantial web app.

Use this file as the default operating guide for agentic coding work.

Agent Role

Agents operating in this repository should treat their role as broader than pure code editing.

• Core principle: answer first, edit second.
• Primary responsibility 1: write, revise, translate, restructure, and improve reading notes based on the user's request.
• Primary responsibility 2: answer the user's questions clearly and directly, including conceptual questions about papers, ML systems, infrastructure, training methods, or repository content.
• Do not assume every request is an implementation task; many valid tasks here are explanation, summarization, comparison, synthesis, or note-writing tasks.
• When a user asks a question, prioritize giving a useful answer before proposing or making file edits.
• Edit files only when the user asks for a persistent change or when a written artifact is the natural deliverable.
• If a request can be satisfied well with explanation alone, do that instead of turning it into an implementation task.
• When editing notes, preserve technical accuracy, existing structure, and the author's naming/language conventions unless the user requests a rewrite.

Rule Files

No repository-specific AI rule files were found.

• No .cursorrules
• No .cursor/rules/
• No .github/copilot-instructions.md

If any of those files are added later, treat them as higher-priority guidance.

Repository Shape

• Root-level directories such as pre-training/, post-training/, agent/, and tech-report/ are mostly Markdown notes.
• The main executable codebase lives in smol-training-playbook/app.
• Most build/test/style guidance below applies to smol-training-playbook/app.
• When editing top-level note files, preserve existing prose structure and filename conventions.

Working Directory

For app work, use:

cd smol-training-playbook/app

Environment

• Node.js >=20 is required.
• Prefer npm as the package manager.
• The repo contains both package-lock.json and yarn.lock, but README, Dockerfile, and scripts all use npm.
• Astro output is static.
• Main frameworks: Astro, MDX, Svelte, D3, Playwright.

Main Commands

Install dependencies:

npm install

Start local dev server:

npm run dev

Build production output:

npm run build

Preview the built site on port 8080:

npm run preview

Export Commands

Export PDF:

npm run export:pdf

Export plain text:

npm run export:txt

Export DOCX:

npm run export:docx

Export LaTeX bundle:

npm run export:latex

Export screenshots/images:

npm run export:images

Export bundle:

npm run export:bundle

Sync template utilities:

npm run sync:template
npm run sync:template:dry
npm run sync:template:force

Importer entry points:

npm run latex:convert
npm run notion:import

Lint / Typecheck / Test Reality

There is currently no standard lint command.

There is currently no standard format command.

There is currently no standard typecheck command.

There is currently no standard npm test script.

There is currently no configured Vitest/Jest/Playwright test runner entrypoint.

Do not invent nonexistent commands in automation or PR instructions.

What To Run For Verification

For most app changes, run:

npm run build

If the change affects an embed or rendering path, also run the relevant ad hoc test script.

If the change affects exporters, run the specific export command you touched.

Single-Test Guidance

"Single test" in this repo means running one standalone script, not filtering within a test runner.

Available standalone test scripts:

node scripts/test-banner.mjs
node scripts/test-embed-selects.mjs
node scripts/test-katex-display.mjs
node scripts/test-tables.mjs

These scripts target http://localhost:4321/?viz=true.

Typical workflow for a single test:

1. Start the dev server with npm run dev.
2. In another shell, run one test script such as node scripts/test-banner.mjs.
3. Check generated output under test-screenshots/ if the script writes screenshots.

If Playwright browsers are missing locally, install them explicitly:

npx playwright install chromium

Importer Subpackages

These subdirectories have their own package manifests:

• smol-training-playbook/app/scripts/notion-importer
• smol-training-playbook/app/scripts/latex-importer

Use local commands inside those folders when changing importer internals.

Examples:

cd scripts/notion-importer && npm install && npm run convert
cd scripts/latex-importer && npm install && npm run convert

Source Layout

• src/pages/: Astro pages
• src/components/: Astro and Svelte UI components
• src/components/trackio/: interactive Trackio component system
• src/content/: MDX article content, bibliography, assets, embeds
• src/styles/: global CSS tokens, layout, and component partials
• plugins/: remark and rehype plugins
• scripts/: export/import/test utilities

Imports

• Use ESM imports everywhere.
• In Astro and Svelte files, prefer import grouping in this order: external packages, local components/modules, then styles.
• Keep component imports explicit rather than wildcarding local UI modules.
• Use relative paths consistent with nearby files.
• Preserve existing import quote style within the file you edit.

Formatting

• In the app codebase, default to 2-space indentation.
• In importer subpackages and some utility files, 4-space indentation exists; preserve the local style of the file.
• App Astro/Svelte/JS files commonly use semicolons; keep them.
• App Astro/Svelte/JS files commonly use double quotes; prefer double quotes in app files.
• Do not reformat unrelated files just to normalize style.

Types

• Astro components often use inline TypeScript in frontmatter.
• Prefer interface Props or small type aliases for component inputs.
• Prefer explicit types for non-trivial helper return values when the shape matters.
• Avoid introducing new any unless interop makes it necessary.
• Existing as any escape hatches exist; reduce them only when doing so safely and locally.
• If a script is intentionally browser-only and difficult to type, follow the surrounding pattern rather than forcing a large refactor.

Naming

• Use PascalCase for Astro and Svelte component filenames.
• Use camelCase for variables, functions, and local helpers.
• Use kebab-case for utility module filenames.
• Use UPPER_SNAKE_CASE only for real constants shared within a file.
• CSS class names commonly follow block, element, modifier patterns such as trackio__grid and html-embed--wide.

Astro Conventions

• Put component logic in the frontmatter block.
• Use is:inline scripts only when DOM or browser APIs are required.
• Prefer composition through components over large monolithic page templates when possible.
• Use set:html only for trusted content paths.
• Keep hydration targeted; use Svelte islands only where interactivity is needed.

Svelte Conventions

• Use export let for props.
• Use $: reactive statements for derived state or side effects that match existing code.
• Use onMount and onDestroy for browser lifecycle work.
• Clean up timers, listeners, and observers when the component owns them.
• Keep imperative DOM work contained and defensive.

MDX And Content Conventions

• Main article content lives in src/content/article.mdx and chapter files under src/content/chapters/.
• Preserve frontmatter structure and citation-friendly content formatting.
• The markdown pipeline supports math, footnotes, directives, citations, wrapped tables, and code-copy UI.
• Prefer reusable components for interactive content instead of embedding large repeated HTML when a component abstraction is sensible.
• For raw embeds, keep source files in src/content/embeds/ and reference them through existing HtmlEmbed patterns.

CSS Conventions

• Reuse design tokens from src/styles/_variables.css before adding new hard-coded values.
• Prefer CSS custom properties over duplicated literal colors and spacing.
• Keep light and dark theme behavior working.
• Use existing custom media aliases where possible.
• The codebase already uses modern CSS features such as oklch, color-mix, @custom-media, and :has().
• Match the existing BEM-like naming style for new classes.
• Preserve print styles when changing content or embed rendering.

Error Handling

• In browser code, prefer graceful degradation for optional APIs.
• Use try/catch around fragile browser-only behavior when failure should not break the page.
• Log meaningful warnings or errors when a fallback path is taken.
• In Node/importer scripts, fail clearly and return a non-zero exit on unrecoverable errors.
• Do not silently swallow important errors unless the surrounding code already intentionally treats them as non-critical.

Editing Guidance

• Favor minimal, local changes.
• Preserve mixed-style files instead of rewriting them wholesale.
• Avoid changing generated outputs unless the task specifically requires regeneration.
• Avoid changing lockfiles unless dependency work requires it.
• If you add a new command, document it here and in the nearest README.

Recommended Verification Matrix

• Content or layout change: npm run build
• Embed behavior change: npm run build plus one relevant node scripts/test-*.mjs
• Trackio interaction change: npm run build and manual browser verification in npm run dev
• Exporter change: run the specific export command you modified
• Importer change: run the importer locally in its own subpackage

Root Markdown Notes

• Top-level note files are primarily documentation, not application code.
• Preserve existing naming patterns such as _en.md and _zh.md suffixes.
• Keep edits content-focused; do not apply app-specific formatting assumptions to research notes.

Interaction Log

• Maintain a root-level log.md as the persistent interaction history for this repository.
• After each user interaction, append a concise entry capturing the user request, the assistant response, and any context needed to resume the conversation later.
• When the conversation involves paper reading, include the current paper identity and the most useful resume point if known.
• Keep entries brief and useful; summarize rather than transcribing long exchanges, and avoid recording unnecessary sensitive details.

Default Agent Behavior

• Work from the repository root, but switch to smol-training-playbook/app for app commands.
• Prefer npm commands over yarn unless the user asks otherwise.
• Verify with npm run build whenever you touch app code and no narrower validation exists.
• When asked for tests, be explicit that this repo uses standalone scripts rather than a formal test runner.