AlexandrAI AGENTS.md
agents-md

AlexandrAI Publishing Format Registry Agent Guide

Project-specific AGENTS.md guidance for the AlexandrAI format registry helper, format resolution, schemas, templates, metadata extraction, template fingerprints, and publish preparation.

AGENTS.md

Guidance for coding agents working on the AlexandrAI report format registry.

Project Overview

The format registry is the binding layer between a format id and its schema, template, fingerprint, metadata contract, browser title, and publish preparation. It prevents reports from drifting away from canonical shells while allowing authored JSON to vary by deliverable.

Project Map

  • skills/alexandrai-publishing/scripts/lib/report-formats.mjs loads the registry and resolves formats.
  • skills/alexandrai-publishing/assets/report-formats/registry.json is the source of format ids and aliases.
  • skills/alexandrai-publishing/assets/report-formats/templates/ contains canonical HTML shells.
  • skills/alexandrai-publishing/assets/report-formats/schemas/ contains JSON Schema contracts.
  • skills/alexandrai-publishing/assets/report-formats/specs/ contains authoring rules.
  • skills/alexandrai-publishing/scripts/alexandrai.mjs calls registry helpers during lint, upload, and version.

Setup Commands

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs formats
node skills/alexandrai-publishing/scripts/alexandrai.mjs lint <report.html> --format <format-id>

Change Rules For Agents

  • Keep registry id, alias, schema, template, and default theme in sync.
  • Replace only #report-data JSON in HTML templates.
  • Keep #alexandrai-metadata separate from schema-governed report data.
  • Preserve template fingerprinting after metadata removal and report-data normalization.
  • Reject unresolved identity placeholders before upload.
  • Derive browser title from report metadata, paper metadata, product name, or format label.
  • Prepare HTML for publish by setting title and adding the browser-title script.
  • Do not weaken schema validation to accept invented fields.

Verification

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs formats
node skills/alexandrai-publishing/scripts/alexandrai.mjs lint <report.html> --format <format-id>

When adding a format, lint a minimal valid sample and a deliberately mismatched shell to confirm the template gate fails.

Security Notes

Canonical templates must remain self-contained. Do not add external scripts, external fonts, external images, raw secrets, or private URLs to template shells or report data.

PR Checklist

  • Registry entry resolves by id and alias.
  • Schema and template paths exist.
  • Fingerprint gate passes only for the canonical shell.
  • Metadata validates against taxonomy allowlists.
  • Upload size checks still run on prepared HTML.