Skip to content

AGENTS.md

Latest commit

 

History

History
205 lines (142 loc) · 10.2 KB

AGENTS.md

File metadata and controls

205 lines (142 loc) · 10.2 KB
Raw

AGENTS.md

Instructions for AI agents working on Zaparoo.org.

Role

This is primarily a documentation project. Treat most tasks as technical writing, source verification, information architecture, or Docusaurus maintenance rather than app development.

Write for Zaparoo users first. Prefer practical, verified guidance over implementation detail unless the implementation changes what a user should do.

Critical rules

  • Do not invent behavior. Verify feature, config, platform, API, and driver claims from the owning project before documenting them.
  • Search existing docs before adding new content, and prefer targeted edits over broad rewrites.
  • Respect generated content and versioned docs boundaries.
  • Ask before changing navigation, URLs, redirects, or release/versioning flows.

Stack and commands

  • Docusaurus 3.10.0 with TypeScript config
  • React 19.2.5
  • TypeScript ~6.0.3
  • Node >=20
  • Package manager: pnpm

Use pnpm for all package commands.

pnpm start          # dev server, binds to 0.0.0.0
pnpm typecheck      # TypeScript check for TS/React/config changes
pnpm build          # full static build into build/
pnpm serve          # serve the built site locally
pnpm clear          # clear Docusaurus cache

Do not run pnpm build speculatively. Run it only when explicitly asked or when verifying a specific build, link, MDX, or Docusaurus issue.

Repository layout

docs/                 Current documentation, with autogenerated sidebar
blog/                 Date-prefixed blog posts: YYYY-MM-DD-slug/index.mdx
src/pages/            Static custom pages such as start, downloads, support
src/components/       Reusable React components for custom pages and MDX
static/               Images, downloads, install scripts, and other assets
versioned_docs/       Older documentation snapshots
versioned_sidebars/   Sidebars for older documentation snapshots

The current docs sidebar is autogenerated from the docs/ tree. Ask before broad information-architecture or sidebar changes.

Documentation areas

Area Purpose Owning source for behavior
docs/platforms/ Install guides, file paths, and platform-specific behavior Usually ZaparooProject/zaparoo-core; platform docs may need upstream platform sources
docs/app/ Zaparoo App setup, mobile features, and web app behavior ZaparooProject/zaparoo-app
docs/designer/ Zaparoo Designer setup, templates, and label design behavior ZaparooProject/zaparoo-designer
docs/readers/ Reader hardware setup, compatibility, and troubleshooting ZaparooProject/zaparoo-core for driver behavior
docs/tokens/ Token types, storage, writing, and physical media guidance ZaparooProject/zaparoo-core for scan/write behavior
docs/zapscript/ ZapScript commands, syntax, and examples ZaparooProject/zaparoo-core
docs/core/ Core service, config, CLI, API, and contributor docs ZaparooProject/zaparoo-core
docs/zapesp32/ ZapESP32 setup and reference docs ZaparooProject/zaparoo-esp32 wiki/source
blog/ Release notes, project updates, and community posts Relevant changelog, source repo, PRs, or release notes
src/pages/ Static landing, downloads, support, legal, and marketing pages ZaparooProject/zaparoo.org
src/components/ React components used by pages and MDX ZaparooProject/zaparoo.org

Platform index.md pages have a dual purpose: each one is copied into its distribution binary as a README.txt file. Keep these pages readable as plain text in basic editors like Notepad. Avoid MDX features, JSX components, and complex Markdown. Do not split platform docs into multiple pages unless a section is extremely long or not useful in a post-install README.

Generated and remote content

These directories are populated by docusaurus-plugin-remote-content and may be overwritten:

  • docs/core/contributing/ from ZaparooProject/zaparoo-core/docs/
  • docs/core/api/ from ZaparooProject/zaparoo-core/docs/api/
  • docs/zapesp32/ from the ZaparooProject/zaparoo-esp32 GitHub wiki

Do not hand-edit generated remote content unless the user explicitly asks and understands the change may be overwritten. Prefer changing the upstream source when applicable.

Documentation workflow

Before writing, identify the page type and audience: install guide, reader page, token page, config reference, release note, blog post, or static page.

Match the structure to the job: install/setup pages need ordered steps, reference pages need accurate tables, concept pages explain what and why, and troubleshooting starts with symptoms and checks.

Do not turn a commit list into a feature dump. Document the user-visible behavior where readers need it, not wherever it sounds new. Keep overview and intro pages focused on stable purpose and primary tasks; put niche features, edge cases, and platform-specific details in the relevant setup, reference, or troubleshooting section.

Search existing docs before adding new content. Prefer the smallest useful change, and push back with sources when a requested change conflicts with verified behavior.

For doc rewrites, read nearby pages first so the structure and links fit the surrounding section. Do not blindly copy older pages if they conflict with the rules here.

Verify behavior before documenting it. Do not claim a feature, platform behavior, default, driver ID, config key, or limitation exists unless it is verified from source code, current generated docs, or a linked upstream source.

For behavior owned by another Zaparoo project, check that project's source or docs before writing. This includes config syntax, defaults, driver IDs, platform support, API behavior, and limitations.

Good docs page pattern

Use this as a compact pattern, not a rigid template:

---
description: "Concrete one-sentence summary of what the page helps users do."
keywords: [zaparoo thing, specific use case]
---

# Page Title

Short intro that explains the user outcome.

## Setup

Steps or config the user can follow.

## Troubleshooting

Common failures and fixes, when useful.

Good docs pages usually have:

  • Concrete frontmatter descriptions and useful keywords
  • A title-case H1
  • A short intro before setup details
  • Steps, tables, or examples where they make action easier
  • Minimal, realistic examples that show the simplest working version first
  • Platform and config notes only when verified
  • Troubleshooting when it prevents common support questions
  • Internal links on first mention of related concepts
  • Technical terms defined on first use

Blog and release notes

Blog posts live in blog/YYYY-MM-DD-slug/index.mdx. Release posts are a major project process, not filler around a changelog.

Write release posts with a concrete opening summary, practical highlights, and enough context for users to understand what changed. Keep the tone casual and specific. First person is fine when it matches the existing blog voice.

Verify release claims from changelogs, source, PRs, or upstream release notes when possible. Do not invent importance or user impact.

Avoid generic hype, vague future-looking conclusions, and exhaustive changelog dumping when a shorter summary would serve readers better.

Keep draft: true unless the user asks to publish or change draft status. The release checklist lives in README.md; do not run release, tag, deploy, or versioning flows unless explicitly asked.

Writing style

These rules apply to all user-facing content: docs pages, blog posts, PR descriptions, release notes, and static pages.

  • Never add "See Also" sections.
  • Never use emojis unless explicitly asked.
  • Page titles and H1s use title case.
  • Section headings use sentence case unless matching a product name, command, or established nav label.
  • Do not use subjective section title words like "Recommended", "Best", or "Preferred" unless part of an admonition label or established product term.
  • Avoid words like "simple", "easy", or "just" when they minimize setup complexity or make users feel at fault.
  • Keep the tone casual, direct, and conversational.
  • Focus on what users need to know; skip exhaustive technical detail.
  • Defer to dedicated docs pages for detailed configuration instead of duplicating it.
  • Never guess implementation details.

Linking and Markdown

  • Link liberally, Wikipedia-style, but only the first mention on a page.
  • Prefer internal links; check whether a docs page exists before linking externally.
  • Use relative links inside docs when practical.
  • Use descriptive link text; avoid generic text like "here" and avoid bare URLs when readable text is better.
  • Check anchors before linking to headings.
  • Avoid changing headings or URLs unless necessary because anchors may already be linked.
  • External links are fine for GitHub repos, specs, stores, and external tools.
  • Use language tags on fenced code blocks where practical.
  • Add useful alt text for images.
  • Use admonitions sparingly for real warnings, tips, or platform-specific notes.
  • Keep frontmatter descriptions concrete and search-friendly.

Verification

For Markdown-only changes, read the final file, check touched links and anchors, search for stale terms or old mistakes when relevant, and inspect the diff.

For TypeScript, React, or Docusaurus config changes, run pnpm typecheck unless there is a clear reason not to.

Run pnpm build only when explicitly asked or when verifying a specific build, link, MDX, or Docusaurus issue.

In the final response, state what was verified and what was not run.

Boundaries

Always:

  • Use pnpm for package management commands.
  • Follow the writing, linking, and source-verification rules above.
  • Respect generated remote content boundaries.
  • Preserve user changes in a dirty worktree.

Ask first:

  • Adding new dependencies.
  • Changing the structure of docusaurus.config.ts.
  • Adding or modifying redirects.
  • Broad information-architecture, sidebar, or URL changes.
  • Major rewrites of generated or versioned docs.
  • Large SEO or metadata strategy changes.

Never:

  • Run pnpm build speculatively.
  • Edit generated remote content casually.
  • Claim a feature exists without verifying it in source or current upstream docs.
  • Commit secrets or API keys.