Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (87 loc) · 3.44 KB

AGENTS.md

File metadata and controls

117 lines (87 loc) · 3.44 KB
Raw

HagiCode Docs - Agent Configuration

Root Configuration

Inherits all behavior from /AGENTS.md at the monorepo root. Local rules extend or override the root file for this repository.

Project Context

This repository is the standalone HagiCode documentation site built with Astro and Starlight.

  • User docs, guides, and reference pages live here.
  • Blog content and release-note related flows also run here.
  • The marketing website lives in repos/site.

Working Directory

Run commands from repos/docs/.

Key Commands

Run from repos/docs/. Most commands chain prepare:docs-runtime first so generated locale resources and the assembled content tree exist before Astro or TypeScript run. For a no-build first pass, use npm run test:fast; it prepares the docs runtime and runs TypeScript checking only, so it does not validate rendered pages or production output. Use the full build commands for release and CI verification.

npm install
npm run dev
npm run build
npm run build:ci
npm run preview
npm run test:fast
npm run typecheck
npm run verify:blog

i18n (hagi18n)

npm run i18n:check      # audit + stale generated-resource check + doctor
npm run i18n:audit
npm run i18n:doctor
npm run i18n:generate   # refresh src/i18n/generated resources
npm run i18n:sync       # dry-run en-US -> zh-CN
npm run i18n:prune      # dry-run prune

Release notes

npm run release-notes:fetch
npm run release-notes:materialize
npm run release-notes:sync
npm run verify:release-notes:input
npm run verify:release-notes:output
npm run test:release-notes

Snapshot sync

npm run sync:articles-snapshot   # structured article snapshot for *-vs-hagicode FAQ routes
npm run sync:tips-snapshot

Screenshots

npm run screenshots:scan-metadata
npm run screenshots:sync

Article images

npm run verify:docs-image-references   # read-only audit of body image references
npm run test:docs-image-references

Tests

npm run test:release-notes
npm run test:runtime-version-index   # vitest; chains prepare:docs-runtime

Translation reporting

npm run report:translation
npm run translate:missing:pi
npm run verify:docs-translation

Key Paths

  • src/content/docs/: documentation and blog content
  • src/content/.generated/docs/: build-time assembled Starlight input tree generated by prepare:docs-content; do not edit directly
  • src/components/: custom site components
  • src/i18n/locales/: source-of-truth YAML UI strings per locale
  • src/i18n/generated/: committed generated locale resources imported by astro.config.mjs
  • src/data/release-notes/: release-note source data and materialized output
  • scripts/: content preparation, verification, and sync tooling
  • tests/: script and content workflow tests

Agent Guidelines

  • Favor clear documentation structure over marketing language.
  • Keep content in Markdown or MDX patterns already established in the repo.
  • Preserve frontmatter, heading structure, internal links, and verification-script expectations.
  • Use repo scripts for content materialization, translation, release notes, and screenshot workflows instead of editing generated output directly.
  • Keep docs-specific concerns here; broader product marketing belongs in repos/site.
  • Tag new calls to action for Google Analytics with gaEventAttributes() and follow the "Analytics events" notes in README.md.

References

  • README.md
  • DESIGN.md
  • scripts/