pagez

AGENTS.md

pagez — Markdown, as pages.

craftz

This repository follows craftz's rules, which set how every repository builds, checks, deploys and releases. Run pnpm craftz rules before changing any of that. It prints the rules for the version this repository installs, and pnpm craftz rules <id> prints one.

  • Change the toolchain, scripts, versions or deploys in craftz first, then bring each repository in line. Don't change them in one repository alone.
  • Open a pull request with pnpm pr "<title>". It branches from main, or adds to the branch's open pull request when given its title, then commits, runs pnpm run verify, pushes and turns on auto-merge, and the pull request is squash-merged once CI passes. Nobody pushes to main. After a merge, pnpm gone deletes the merged branches.
  • To see what's live, run pnpm craftz status: CI, pull requests, the release and the site. --notes adds the release's notes, and --log the build's log. Use it rather than reading GitHub, npm or Cloudflare another way.
  • In a package, give it one label for the release notes, pnpm pr "<title>" --label <label>: breaking, added, fixed, improved, docs, or internal for tests, tooling, site and lessons. CI fails without one.
  • Run tools through pnpm run … and pnpm exec, not global installs.
  • A held check is a tool's limit, not a choice. The rules give its reason, so leave it until the reason goes away.

Prose

Explanations go in @prose comments. Run pnpm prose rules before writing prose, or changing code a @prose comment explains. It prints the rules for the version this repository uses, each with the codes that check it, and pnpm prose rules <code> says what one warning asks for. The rules live in prose's usage and aren't copied here, so every repository writes to the same rules.

After writing prose, run pnpm prose style <files> on the files you changed, and take its advice where it reads better. It always passes, so it's advice, not a check.

This repository

  • The docs describe Pagez alone, with no other tool's history and no one site's names in them. Package and tool names stay, such as @amitkaps/pagez and craftz's URLs, since they're what's published. History keeps its reason and drops its source, and evidence keeps its finding with a neutral example.
  • The plan looks forward: what's next, in order, and what works now. What a piece of work taught goes in docs/lessons.md, and what it shipped is in git and the release notes.