Skip to content

chore: add AGENTS.md satellite context file #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rz1989s merged 1 commit into from
Jul 14, 2026
Merged

chore: add AGENTS.md satellite context file #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<!-- Satellite context file — extends the global hub (~/.claude/CLAUDE.md | ~/.pi/agent/AGENTS.md). Host-neutral; project-specific only. Do not duplicate hub standards here. -->

# pi-package-index

> **Unofficial** community index of [Pi coding-agent](https://github.com/earendil-works/pi) packages — ranked by downloads + GitHub stars + maintenance health, with filterable search and a public JSON API. Live at **pi-package.rectorspace.com**. Not affiliated with or endorsed by earendil-works.

## What

The official `pi.dev/packages` gallery lists ~4,300 npm packages tagged `pi-package` but lacks GitHub stars, maintenance signals, robust filtering, and a working API. This project fills those gaps:

- **Ranked** by npm downloads/mo + GitHub stars + last push + maintained badge.
- **Searchable & filterable** by type, category, min-downloads, min-stars, maintained-only.
- **Public JSON API** at `/api/packages` (the official `pi.dev/api/packages` returns 501).
- **Daily refreshed** via a GitHub Actions cron that commits `data/packages.json`.

## Stack

Next.js 15 (App Router, SSG) · TypeScript strict · Tailwind v4 · Lucide · FlexSearch · Vercel (hobby) · pnpm. No backend, no database — see `SPEC.md` for the full architecture.

## Common Commands

```bash
pnpm install
pnpm dev # local app
pnpm build # next build (runs prebuild copy-data first)
pnpm start # next start
pnpm typecheck # tsc --noEmit
pnpm lint # eslint .
pnpm pipeline # regenerate data/packages.json (needs npm + GitHub access; CI uses GITHUB_TOKEN)
pnpm pipeline:readmes # regenerate READMEs
```

## Data Sources

- npm registry (`keywords:pi-package`) + npm downloads API
- GitHub REST API (stars, last push, open issues, archived) via the CI `GITHUB_TOKEN`

Refreshed daily at 04:00 UTC. The `generatedAt` field in every response tells you the index age.

## Deployment

Vercel (hobby). The GitHub Actions cron commits `data/packages.json` daily; the app is statically regenerated from that file.

## Notes

- Add a package by publishing to npm with the `pi-package` keyword — it appears on the next refresh.
- See the [Pi package docs](https://github.com/earendil-works/pi/blob/main/docs/packages.md).
Loading