AlexandrAI AGENTS.md
agents-md

AlexandrAI Publishing CLI Validation Agent Guide

Project-specific AGENTS.md guidance for the AlexandrAI CLI validation and publication path, auth, lint, upload, versioning, history, output archival, and error handling.

AGENTS.md

Guidance for coding agents working on AlexandrAI CLI validation and publication.

Project Overview

The CLI is the operational surface for all publishing work. It parses commands, loads local auth, lints artifacts, uploads new items, publishes versions, records local history, prints machine-readable responses, and creates dated output directories for generated artifacts.

Project Map

  • skills/alexandrai-publishing/scripts/alexandrai.mjs implements parse(), loadAuth(), lintFile(), upload(), versionPaper(), historyCommand(), ensureOutputDir(), archivePublished(), outdirCommand(), search(), fetchPaper(), and printUntrustedResponse().
  • skills/alexandrai-publishing/scripts/lib/report-formats.mjs provides format helpers used by lint and upload.
  • skills/alexandrai-publishing/references/API.md documents endpoint and local credential behavior.
  • skills/alexandrai-publishing/SKILL.md defines the required lint-before-upload workflow.

Setup Commands

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs formats
node skills/alexandrai-publishing/scripts/alexandrai.mjs outdir
node skills/alexandrai-publishing/scripts/alexandrai.mjs history
node skills/alexandrai-publishing/scripts/alexandrai.mjs lint <artifact> --format <format-id>

Change Rules For Agents

  • Keep lint as the gate before upload and version.
  • Print server validation responses unchanged when upload or version fails.
  • Keep local history best-effort; server publication must not depend on local logging.
  • Archive successful uploads into the dated output directory.
  • Keep graph search and fetch output wrapped as untrusted third-party content.
  • Keep auth token local-only and out of logs.
  • Preserve max upload size enforcement.
  • Keep command names stable because SKILL.md and references document them.

Verification

bashnode skills/alexandrai-publishing/scripts/alexandrai.mjs formats
node skills/alexandrai-publishing/scripts/alexandrai.mjs outdir
node skills/alexandrai-publishing/scripts/alexandrai.mjs history

For upload-path changes, test both HTML and markdown-native lint paths before publishing.

Security Notes

Never echo auth credentials, local credential file contents, machine-specific paths, private endpoints, or raw bearer values in user-facing output or public artifacts.

PR Checklist

  • Unknown commands still fail clearly.
  • Lint runs before upload and version.
  • History append is best-effort.
  • Untrusted graph content is enveloped.
  • Upload size checks remain active.