AGENTS.md

Guidance for coding agents working on AlexandrAI packages/shared. This package is the format, taxonomy, template, and validation core shared by the app and publishing tooling.

Project Overview

packages/shared exports taxonomy helpers, report format registry helpers, canonical template handling, and validation logic. It also carries report-format schemas, specs, templates, research-paper assets, chart examples, icons, category and language data, and tests for taxonomy, templates, validation, and references.

Validation behavior here controls what the public archive accepts. Treat every schema, template, metadata, and research-audit change as a public contract change.

Project Map

• src/index.ts re-exports taxonomy, formats, template, and validation modules.
• src/taxonomy.ts reads and validates category and language taxonomy values.
• src/formats.ts resolves report formats, schemas, templates, metadata script patterns, and template fingerprints.
• src/template.ts provides canonical template HTML handling.
• src/validation.ts extracts report data, extracts metadata, validates schemas, validates taxonomy, enforces research-paper audit thresholds, and returns structured validation errors.
• src/assets contains research-paper assets and the report-formats directory: schemas, specs, templates, format design notes, chart examples, icons, category data, and language data.
• Tests live beside modules as taxonomy, template, validation, and reference tests.

Setup Commands

~bash npm run build -w @aipaper/shared npm run test -w @aipaper/shared npm run test npm run typecheck ~

The build copies assets into dist. If asset paths or package exports change, verify the built dist contains required schemas, templates, icons, taxonomy, and format assets.

Change Rules For Agents

• Do not weaken validation to make a single bad artifact pass. Fix the artifact or add a justified format evolution.
• Keep format ids, schema files, specs, templates, and registry helpers synchronized.
• Preserve taxonomy allowlist behavior for language and category ids.
• Treat research-paper audit thresholds as policy; changes need tests and clear rationale.
• Keep metadata extraction paths compatible with current HTML formats and markdown-native sidecar behavior.
• If a schema changes, update the matching spec and template assumptions.
• Avoid adding runtime-only local paths or machine-specific assumptions to assets.

Verification

~bash npm run test -w @aipaper/shared npm run build -w @aipaper/shared ~

For format changes, add or update validation fixtures and run the app tests that exercise upload or public rendering.

Security Notes

Validation protects public publication. Do not allow scripts, external asset fetches, private endpoints, secret-bearing metadata, oversized payloads, or format confusion through schema or template shortcuts. Keep error messages actionable but redacted.

PR Checklist

• Schema, spec, template, and format registry remain aligned.
• Validation tests cover accepted and rejected cases.
• Taxonomy changes are deliberate and tested.
• Built assets are present after package build.