---
name: bansos-add-entry
description: Add or review a new bansos.dev listing efficiently. Use when an AI agent needs to research a promo/freebie/program source, convert it into validated bansos.dev data, run or prepare `npx bansosdev add`, create/update a submission issue or PR, or check whether a proposed bansos entry follows wauputr4/bansos contribution rules.
---

# Bansos Add Entry

## Goal

Turn a source link or user-provided promo details into one clean bansos.dev entry with clear evidence, contributor attribution, and a valid submission path.

## Workflow

1. Read the source page or user-provided evidence before writing copy. If the source is current, browse or otherwise verify the latest terms, dates, pricing, quotas, and eligibility.
2. Extract only fields supported by bansos.dev: `id`, `title`, `provider`, `description`, `benefits`, `promoCode`, `validity`, `requirements`, `tips`, `publishedAt`, `contributor`, `ctaLink`, `tags`, `featured`, and `status`.
3. Prefer the public CLI path unless the user explicitly asks for maintainer/direct mode.
4. Validate locally with `npx bansosdev add ... --mode json` before asking a user to submit, opening an issue, or preparing a PR.
5. If the user asks you to implement directly in the repo, update `src/lib/data/bansos.json` through the repo script where possible and preserve existing formatting.
6. Create a concise PR/issue body that mentions the source link, contributor, validity, and any uncertainty.

## Data Rules

- Use kebab-case lowercase IDs, for example `tokenrouter-dev-credits`.
- Keep `benefits` and `requirements` as short lists; split CLI values with `|`.
- Use comma-separated `tags`, for example `AI,Gratisan,Course`.
- Use `validity.type` as `fixed`, `uncertain`, or `forever`.
- For `fixed`, include a real calendar date as `validity.date` in `YYYY-MM-DD`.
- Use `publishedAt` in `YYYY-MM-DD`; reject impossible dates like `2026-02-31`.
- Set `status` to `active`, `expired`, or `upcoming` based on source evidence and current date.
- Always include both `contributor.name` and `contributor.url` when contributor metadata is known.
- Keep claims traceable. If a benefit is community-reported, say so in copy or `tips` instead of presenting it as guaranteed.

## CLI Pattern

Use this shape for public submissions:

```bash
npx bansosdev add \
  --id contoh-bansos \
  --title "Contoh Bansos Developer" \
  --provider "Provider" \
  --description "Deskripsi singkat bansos." \
  --benefits "Benefit satu|Benefit dua" \
  --validity-type fixed \
  --validity-date 2026-06-30 \
  --validity-desc "Selama kuota masih ada" \
  --published-at 2026-06-13 \
  --requirements "Buat akun|Klaim program" \
  --cta-link "https://example.com" \
  --contributor-name "Nama Kontributor" \
  --contributor-url "https://example.com" \
  --tags "Cloud,Gratisan" \
  --status active \
  --mode json
```

After JSON validation, run the same command without `--mode json` to get the GitHub issue URL.

For maintainers only, use `--mode direct` with `BANSOSDEV_GITHUB_TOKEN` when the user has explicitly provided or configured the token.

## References

- Read `references/bansos-entry-rules.md` when you need field-level guidance, PR rules, or example issue/PR wording.