AGENTS.md git:20260824.7a7f282A

Immutable. This exact content is served forever at /api/v1/blob/db6e78d40db7e933.

# Repository instructions

This repository is the **plugin catalog**: the awesome list (`catalog/plugins/*.json`),
the plugin submission review/merge workflow, and the generated README directories. The
DSH 1024Store application — the deepseek1024.com site, its Worker, and the `dsh1024` npm
package — lives in [imsai-sh/dsh1024-oss](https://github.com/imsai-sh/dsh1024-oss).

## The submission gate is the product

- The public PR gate accepts changes to `catalog/plugins/*.json` only; everything else is
  maintainer-bypass territory. `scripts/review-plugin-submission.mjs` is the trusted
  reviewer: it always runs from the base branch and treats the submitted checkout as data.
- The `allow-unsafe-pr-checkout: true` flag in `.github/workflows/plugin-review.yml` must
  never be removed — without it every fork PR fails silently with no comment.
- Verdicts are three-state: exactly one new entry on a non-draft PR auto-merges;
  updates/removals go green but wait for a maintainer; anything else fails with a comment.
  A failed review never closes the PR.
- `skills/submit-dsh-plugin/` must stay in lockstep with the live submission spec: any
  change to CONTRIBUTING.md, the schema or categories, the PR template, the review
  workflow or scripts, or the merge flow updates the skill, its references, scripts,
  tests, and README install instructions in the same change.

## Generated files

- `README.md` and `catalog/README.md` are bot-generated by `scripts/build-readme.mjs`.
  Never hand-edit them; change the generator and run `npm run readme:build`. The
  catalog-sync workflow regenerates and force-pushes them via the `CATALOG_DEPLOY_KEY`
  deploy key, which is also the documented branch-protection bypass.
- The README hero screenshot lives on the orphan `assets` branch of THIS repository,
  force-pushed by the catalog-sync workflow. Do not repoint it elsewhere.
- The WeChat group QR image is `docs/assets/wechat-group.jpg` in this repository (the
  site serves its own copy from the other repo).

## Cross-repo contracts (no CI spans both repositories)

The deployed Worker's source lives in dsh1024-oss; these pairs drift silently, so check
the other repo whenever you touch one side:

- `scripts/lib/catalog-entry.mjs` id validation ↔ `apps/web/worker/lib/plugin-id.ts` and
  the sync endpoint's `ENTRY_ID`/`ENTRY_KEYS` in `apps/web/worker/app.ts` (dsh1024-oss).
  Drift means a PR passes review here but the sync endpoint rejects it there.
- `catalog/categories.json` here is the source of truth; dsh1024-oss carries a vendored
  mirror bundled into the Worker. A category change lands in both repositories and only
  reaches the site when that Worker is redeployed.
- `scripts/review-plugin-submission.mjs` `classifyGitInstall` ↔
  `apps/web/worker/lib/install-methods.ts` (dsh1024-oss).
- `scripts/build-readme.mjs`'s unclassified label ↔ `UNCLASSIFIED_CATEGORY` in
  `apps/web/worker/lib/categories.ts` (dsh1024-oss).
- `scripts/sync-catalog.mjs` POSTs to `https://deepseek1024.com/api/v1/catalog/sync` with
  `Bearer CATALOG_SYNC_TOKEN`. The token value must match between this repo's Actions
  secret and the Worker secret in dsh1024-oss; rotating it is a coordinated change.
- This repo's CI (catalog-sync) reads the live site: `npm run readme:build` pages
  `/api/v2/plugins`, and the screenshot step captures the deployed homepage. A bad deploy
  from dsh1024-oss turns catalog-sync red or stale — that is expected, not a bug here.

## Permanent URLs

- `docs/install-analytics.md` is a permanent redirect stub: already-published `dsh1024`
  versions print that URL in their telemetry notice. Never delete or rename it.
- The skill install slug `imsai-sh/awesome-deepseek-harness-plugins` and the store's own
  plugin id (same string) are public identity. The id keys live D1 rows and
  `/api/v1/self/update` in the other repo; leave the catalog self-entry
  (`catalog/plugins/imsai-sh--awesome-deepseek-harness-plugins.json`) byte-stable unless
  a coordinated migration is planned.