Repository guidance

This repository is a paper-reading skill with a CommonJS Node.js renderer and a static gallery. Use Node.js 20 or newer. Check git status --short and the relevant diff before editing; preserve unrelated changes. Follow existing scripts and dependencies without installing another workflow framework.

Commands

Run from the repository root:

npm ci
npm run doctor
npm test
npm run build:examples
npm run check:examples
npm run build:docs
npm run check:docs
npm run check:audit
npm run init:reading -- --help
npm run pack:skill -- --help

doctor uses a synthetic smoke fixture, not a real paper. init:reading creates unfinished sources, not completed readings. pack:skill builds a local runtime directory and optional archive; test packages in temporary locations, never by replacing an active personal installation.

Sources and generated files

• SKILL.md is the execution entry point. references/ defines reading and rendering contracts; evals/ defines quality gates and reader tasks.
• README.md and README.zh-CN.md generate docs/index.html and docs/zh.html through npm run build:docs. Keep their gallery order and factual claims aligned.
• examples/*-deep-read.md and their local visual inputs generate docs/*-deep-read.html through npm run build:examples. Register new readings in both READMEs and add reader tasks in evals/reader-tasks.md.
• reports/*.md generate matching docs/*.html through npm run build:audit; retain historical reports as dated snapshots. check:audit checks their freshness.
• Change the source, rebuild, and include generated outputs together. Do not hand-edit generated HTML. A local build does not confirm a live GitHub Pages deployment.
• Homepage controls use BoardUI source in components/ and utils/; styles/site.css compiles to docs/style.css as part of build:docs. Keep semantic colors, composite typography, and upstream attribution in styles/BOARDUI.md. React and Tailwind are build-only development dependencies, excluded from the installable reading runtime.
• Runtime scripts can depend on scripts/lib/ and scripts/fixtures/; keep those helpers in lightweight packages. Keep package-lock.json consistent with package.json.

Reading integrity

• Declare <!-- paper-reading-lang: en --> or <!-- paper-reading-lang: zh-CN --> on the first source line; use the documented optional theme marker and declare <!-- paper-reading-mode: brief --> or <!-- paper-reading-mode: deep --> in the header. Brief is the default; Deep requires the reconstruction protocol and all applicable depth dimensions at 3. Keep readings.json mode metadata aligned with gallery sources.
• Identify the paper and exact version. Keep reported results, author interpretation, redraws, and teaching examples distinguishable; attach source locations to consequential claims.
• Read the available full source and record missing sections or version conflicts. Do not describe abstract-only or incomplete work as a complete deep read.
• Use understanding checks when they help reconstruct, apply, or assess evidence. Native answer disclosures are learning aids, not comprehension scores.
• Distinguish automated structure checks, AI-assisted source checks, experimental reproduction, and independent human evaluation. Report actual checks and unresolved limits; never infer scientific correctness or human learning from a passing render.
• Verify changed CLI behavior with relevant tests, and run generated-file freshness checks after source changes. Inspect rendered pages at narrow and wide widths when presentation changes.