AGENTS.md · diff
git:20260929.b133972 to git:20260930.379d711
20 added, 54 removed. Audit A to A.
- # anymd — agent notes
+ # anymd
- anymd (formerly Citra and pdf-reader-mcp) turns any file into Markdown for AI
- agents. It is one Rust binary (`crates/anymd`) that is both the MCP server and
- the CLI, published to npm as `@sylphx/anymd`. Project facts are in `PROJECT.md`;
- publishing is in `docs/PUBLISH.md`.
+ anymd turns any file into Markdown for AI agents: one Rust binary (`crates/anymd`) that is both the MCP server and the CLI, published to npm as `@sylphx/anymd`. Goal, boundaries and target metrics are in [docs/vision.md](docs/vision.md); the release process is in [docs/PUBLISH.md](docs/PUBLISH.md). Company standards: <https://github.com/SylphxAI/owner/tree/main/standards>.
## Layout
- - `crates/anymd`: the binary: MCP server on rmcp (stdio and Streamable HTTP),
- CLI, `setup` (client registration from mcp-kit) and `version`.
- - `crates/anymd-core`, `anymd-pdf`, `anymd-formats`: conversion (published to crates.io); `anymd-wasm`:
- the docs playground build.
- - `packages/anymd`: the npm package; `bin/anymd.js` is mcp-kit's launcher, which
- runs the matching `packages/npm/<platform>` binary. `packages/aliases/*` are
- `@sylphx/citra` and `@sylphx/pdf-reader-mcp`, which run the same launcher.
- - `test/`: TypeScript tests that spawn the cargo-built binary over MCP.
-
- ## Boundary hazards
-
- - Local-first privacy: do not upload documents or call remote providers unless
- the caller explicitly selects a remote provider adapter.
- - No hosted auth, billing, storage, tenancy or customer-account state here.
- - Optional OCR, vision and region providers stay behind typed adapters that
- fail closed.
- - Public MCP schemas are contracts: version and regression-test option and
- output shapes. The Rust server is their only authority.
- - Keep page, region and source provenance on extraction and analysis outputs.
- - Publishing happens only in `release.yml` on `main`, because npm trusted
- publishing accepts that workflow alone; a version bump PR is the release.
- The same workflow publishes the Rust crates to crates.io (`anymd`, `anymd-core`,
- `anymd-formats`, `anymd-pdf` and the forks `anymd-pdf-extract`,
- `anymd-adobe-cmap-parser` from `vendor/`).
- - Never commit secrets, private documents or customer data.
-
- ## Commands
-
- ```bash
- bun install --frozen-lockfile
- bun run check # Biome
- bun run check:versions # every manifest carries one version
- bun run typecheck
- bun run build # cargo build --release -p anymd
- bun run test:rust
- bun run test:cov # needs the built binary
- bun run docs:build
- bun run check:github-actions
- ```
-
- `ANYMD_BIN=/path/to/anymd` points the tests and the npm launcher at a binary
- built elsewhere (for example under `CARGO_TARGET_DIR`).
+ - `crates/anymd`: MCP server on rmcp (stdio and Streamable HTTP), the CLI, `setup` and `version`.
+ - `crates/anymd-core`, `anymd-pdf`, `anymd-formats`: conversion, published to crates.io. `anymd-wasm`: the docs playground.
+ - `packages/anymd`: the npm launcher, which runs the matching `packages/npm/<platform>` binary. `packages/aliases/*` are the `@sylphx/citra` and `@sylphx/pdf-reader-mcp` aliases.
+ - `test/`: TypeScript tests that spawn the built binary over MCP. `bench/`: AgentDocBench. `brand/`: brand masters.
- ## Releasing
+ ## Hard lines
- `bun scripts/set-version.ts X.Y.Z`, `cargo update -w`, and a `## X.Y.Z` section
- in `CHANGELOG.md`, in one pull request. Merging publishes it through the shared
- mcp-kit workflow; the post-release check is `npx -y @sylphx/anymd@X.Y.Z version`.
+ - Documents stay local. Uploading them or calling a remote provider happens only when the caller selects one, because privacy is the product.
+ - No hosted auth, billing, storage or tenancy state here, so the package stays a plain local tool.
+ - Public MCP tool schemas are contracts. Version them and regression-test option and output shapes; the Rust server is their only authority.
+ - Extraction and analysis outputs keep page, region and source provenance, so agents can cite them.
+ - OCR, vision and region providers sit behind typed adapters that fail closed.
+ - Publish only through `release.yml` on `main`, because npm trusted publishing accepts that workflow alone. A version-bump pull request is the release.
+ - Commit no secrets, private documents or customer data.
- ## Reporting
+ ## How a result is judged
- Report each layer separately: local diff, merged source, published npm
- version, MCP Registry entry.
+ - Pull request checks (`.github/workflows/ci.yml`): `Validate Code Quality`, `security:secrets`, `Plain language`, `Identifiers`. Locally: `bun run check`, `bun run check:versions`, `bun run check:copy`, `bun run typecheck`, `bun run build`, `bun run test:rust`, `bun run test:cov`, `bun run docs:build`, `bun run check:github-actions`.
+ - Accuracy and speed: AgentDocBench (`bench/`, [Benchmark workflow](.github/workflows/benchmark.yml)). A converter change is judged by its score, reading order, table F1, time and tokens against the committed results.
+ - Public copy comes from `product.json` and `bench/leaderboard.py`: edit those and run `bun scripts/render-copy.ts`; `bun run check:copy` fails on drift. Brand files come from `brand/`: run `python3 brand/build.py` after editing.
+ - After a release: `npx -y @sylphx/anymd@X.Y.Z version`.
+ - `ANYMD_BIN=/path/to/anymd` points the tests and the launcher at a binary built elsewhere.