Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (41 loc) · 3.78 KB

AGENTS.md

File metadata and controls

58 lines (41 loc) · 3.78 KB
Raw

Agent Rules

Dependencies

  • Always use the latest stable version of npm packages. Do not pin to older versions.
  • When adding a new dependency, use the package manager (e.g. pnpm add <pkg>) to fetch the latest version. Do not manually write version numbers.
  • Periodically check for outdated packages with pnpm outdated and update them.

Portless

All apps and examples with dev servers use portless to avoid hardcoded ports. Portless assigns random ports and exposes each app via .localhost URLs.

Naming convention:

  • Docs app: docs.wterm → docs.wterm.localhost
  • Examples: <name>.wterm → <name>.wterm.localhost

When adding a new app or example that runs a dev server, wrap its dev script with portless <name>:

{
  "scripts": {
    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
    "dev": "portless my-example.wterm next dev --turbopack"
  }
}

Do not add --port flags — portless handles port assignment automatically. Do not add portless as a project dependency; it must be installed globally.

Documentation

For any user-facing change (new feature, option, API change, bug fix, etc.), update all relevant documentation:

  • Docs content (apps/docs/content/docs/): Update the corresponding MDX pages (e.g. get-started.mdx, vanilla.mdx, react.mdx, configuration.mdx, themes.mdx). Geistdocs renders the frontmatter title; do not repeat it as an H1 in the body. Tables in MDX must use <table> HTML elements, not markdown table syntax. Public URLs remain at the site root.
  • Root README (README.md): Keep the package table, features list, and development instructions current.
  • Package READMEs: Each package under packages/@wterm/ has its own README.md. Update the relevant one when its API, options, or usage changes.
  • @wterm/core README: Must link to every other @wterm/* package. When adding or removing a package, update the "Related Packages" section in packages/@wterm/core/README.md.
  • Navigation (apps/docs/content/docs/meta.json): Update if adding or renaming pages. Shared docs behavior and WebMCP are configured in apps/docs/src/lib/geistdocs/config.tsx.
  • Page titles (apps/docs/src/lib/page-titles.ts): Update if adding new pages.
  • Example READMEs: Each example under examples/ must have a README.md covering what it does, setup steps, how it works, and key files.
  • Code examples in docs: Ensure import paths match the current package structure (e.g. @wterm/dom for vanilla JS, @wterm/react for React).

Use the technical-writer skill (.agents/skills/technical-writer/SKILL.md) when you write or edit prose for this repo, including docs pages, READMEs, changelog entries, commit messages, PR descriptions, and issues.

Releasing

Releases are manual, single-PR affairs. The maintainer controls the changelog voice and format. All @wterm/* packages share a single version number.

To prepare a release:

  1. Create a branch (e.g. prepare-v0.2.0)
  2. Bump the version in packages/@wterm/core/package.json
  3. Run pnpm sync-versions to update all other @wterm/* packages
  4. Write the changelog entry in CHANGELOG.md, wrapped in <!-- release:start --> and <!-- release:end --> markers
  5. Remove the <!-- release:start --> and <!-- release:end --> markers from the previous release entry (only the latest release should have markers)
  6. Open a PR and merge to main

CI compares the version in packages/@wterm/core/package.json to what's on npm. If it differs, it builds, publishes all @wterm/* packages, and creates the GitHub release automatically. The release body is extracted from the content between the markers.