docs: update usage

Author: Junyi-99

AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Application code lives in `src/`, with `app.ts` wiring Express routes, Zod validation, and agent orchestration. Domain-specific agents sit in `src/agents/` (classification, scoring, weakness matching), while parser utilities are under `src/common/`. Shared HTTP middleware lives in `src/middleware/`, and user-facing templates are stored in `src/templates/` (copied into `dist/templates/` during builds). Jest specs such as `src/app.test.ts` keep tests close to the code under test, and the `test/` directory holds sample LaTeX and JSON fixtures for manual runs and regression data.
+
+## Build, Test, and Development Commands
+Use `make dev` for a hot-reloading Docker dev stack (`api-dev` service). Run the prod stack with `make build && make up`, and tear it down with `make down`. Local Node workflows use npm scripts: `npm run start` boots the TypeScript server via ts-node, `npm run build` compiles to `dist/` and copies templates, `npm run serve` runs the compiled output, and `npm test` executes Jest suites (pair with `npm run test:coverage` for coverage details). `make test` wraps the Docker dev stack around the Jest command for parity with CI containers.
+
+## Coding Style & Naming Conventions
+TypeScript targets ESNext with CommonJS modules; keep async flows await-based and prefer typed helpers over `any`. Follow the existing two-space indentation and trailing comma style found in `src/app.ts`. Classes and agents use PascalCase (`PaperScoreAgent`), helpers use camelCase, and schema constants stay in SCREAMING_SNAKE cases only when truly constant. Validate inputs with Zod schemas and centralize repeated parsing logic in `src/common/`. Run `npm run build` before committing to catch TypeScript type drift.
+
+## Testing Guidelines
+Jest with ts-jest powers unit and request tests; new suites should live alongside the modules as `*.test.ts`. Keep test names descriptive ("should parse sections with anchors") and arrange Arrange-Act-Assert blocks clearly. Call `npm test` locally before pushing, and gate high-risk changes with `npm run test:coverage` (aim for no coverage regressions on parser and agent modules). Use `supertest` when exercising Express routes.
+
+## Commit & Pull Request Guidelines
+Recent history uses concise, prefixed commits (`feat:`, `fix:`, `chore:`, `add:`); continue that format with imperative subject lines under ~72 chars. Each pull request should describe the change, note affected endpoints or agents, and link tracking issues. Include repro or test instructions (e.g., `npm test`, `make dev`) and screenshots or JSON samples when responses change.
+
+## Security & Configuration Tips
+Never commit `.env` files or keys; set `MCP_BASIC_KEY` and `MCP_PAPERSCORE_KEY` in your shell or Docker `.env`. Confirm `templatesPath` resolves inside the container before exposing routes, and rotate API keys if logs (via `make logs`/`dev-logs`) ever show accidental dumps.

Makefile

@@ -1,8 +1,6 @@
-# Docker 操作快捷命令
-
 .PHONY: build up down dev dev-down logs clean test
 
-# 生产环境
+# Production environment
 build:
 	docker-compose build
 
@@ -15,7 +13,7 @@ down:
 logs:
 	docker-compose logs -f api
 
-# 开发环境
+# Development environment
 dev:
 	docker-compose -f docker-compose.dev.yaml up --build
 
@@ -25,28 +23,28 @@ dev-down:
 dev-logs:
 	docker-compose -f docker-compose.dev.yaml logs -f api-dev
 
-# 测试
+# Testing
 test:
 	docker-compose -f docker-compose.dev.yaml up -d
 	docker-compose -f docker-compose.dev.yaml exec api-dev npm test
 	docker-compose -f docker-compose.dev.yaml down
 
-# 清理
+# Cleaning
 clean:
 	docker-compose down -v --rmi all
 	docker-compose -f docker-compose.dev.yaml down -v --rmi all
 
-# 重建
+# Rebuilding
 rebuild:
 	docker-compose down
 	docker-compose build --no-cache
 	docker-compose up -d
 
-# 查看状态
+# Checking status
 status:
 	docker-compose ps
 
-# 进入容器 shell
+# Enter container shell
 shell:
 	docker-compose exec api sh
 

README.md

@@ -20,6 +20,10 @@ make logs
 make clean
 ```
 
+## Usage Documentation
+
+For a full walkthrough covering local setup, publishing to GitHub Container Registry, pulling the latest images, and the GitHub Actions pipeline, see [USAGE.md](./USAGE.md).
+
 ### Required environment variables for image
 
 ```bash

USAGE.md

@@ -0,0 +1,42 @@
+# Repository Usage Guide
+
+## Getting Started
+1. Install dependencies: `npm install`.
+2. Copy `.env.example` to `.env` and set `MCP_BASIC_KEY`, `MCP_PAPERSCORE_KEY`, and any other secrets required by the agents.
+3. Run `npm run start` to boot the API via ts-node, or use `make dev` for the auto-rebuilding Docker dev stack (`api-dev` service). `make build && make up` builds and starts the production docker-compose stack locally.
+
+## Local Testing and Builds
+- `npm test`: runs the Jest suites in `src/*.test.ts` and any request tests.
+- `npm run test:coverage`: produces a coverage report under `coverage/`.
+- `npm run build`: compiles TypeScript into `dist/` and copies `src/templates/`.
+- `npm run serve`: executes the compiled `dist/app.js` using Node.
+Use these commands locally before pushing to keep CI green.
+
+## Publishing to GitHub Container Registry (GHCR)
+The repository publishes multi-architecture images to `ghcr.io/<owner>/paperdebugger-mcp-server` via the `Build and Push Docker Image` workflow (`.github/workflows/build.yaml`). When you push to `main` or open/update a pull request targeting `main`, GitHub Actions:
+1. Checks out the repo (with submodules) using `actions/checkout`.
+2. Sets up Buildx and authenticates to GHCR with `${{ secrets.GITHUB_TOKEN }}`.
+3. Generates tags for the branch, PR, and short SHA through `docker/metadata-action`.
+4. Builds `docker/Dockerfile` for `linux/amd64` and `linux/arm64` and pushes all tags to GHCR.
+Manual publishing is rarely needed, but you can mimic the pipeline locally: `docker build -t ghcr.io/<owner>/paperdebugger-mcp-server:dev -f docker/Dockerfile .` and then `docker push ghcr.io/<owner>/paperdebugger-mcp-server:dev` after `docker login ghcr.io` with a PAT scoped to packages.
+
+## Pulling the Latest Image from GitHub
+To consume the newest container, pull the tag emitted by the workflow:
+```bash
+docker pull ghcr.io/<owner>/paperdebugger-mcp-server:main
+docker pull ghcr.io/<owner>/paperdebugger-mcp-server:main-<short_sha>
+```
+Tags `main`, `pr-<id>`, and `<branch>-<short_sha>` are updated during each run; production deployments typically use the `main` tag or a specific SHA tag for reproducibility.
+
+## GitHub Actions Overview
+### Build and Push Docker Image
+- **Trigger:** push to `main` or PR targeting `main`.
+- **Inputs:** repository source, `${{ secrets.PERSONAL_ACCESS_TOKEN }}` for checkout, `${{ secrets.GITHUB_TOKEN }}` for GHCR login.
+- **Process:** checkout → Buildx setup → tag calculation → multi-arch build → push to GHCR (with caching via `type=gha`).
+- **Output:** versioned Docker images stored in GHCR plus workflow metadata (tags, labels).
+
+### Test Coverage Workflow
+- **Trigger:** push or PR against `main` or `develop`.
+- **Inputs:** codebase, Node 20 runtime, secrets like `MCP_AUTO_TEST_KEY` for OpenAI calls.
+- **Process:** checkout → `npm ci` → `npm run test:coverage` → upload `coverage/` artifact → append summary → comment on PR (when applicable).
+- **Output:** stored coverage artifact, GitHub step summary, and a PR comment showing line/function/branch/statement coverage.