Tool-agnostic project instructions for any coding agent (Codex, Cursor, Copilot, Windsurf, Claude Code, ...). Claude Code reads this via
@AGENTS.mdinCLAUDE.md.
This file is the hard rules and nothing else:
what can go badly wrong in THIS checkout and is not obvious from the code, each in a few lines with a link to the detail.
Explanation, history and reference belong in .rules/, the decision index, .memory/ or docs.nemar.org, never here:
two copies drift (ADR 0057).
Read the hard rules in full before you edit anything, and follow a link when you touch that area.
- Public pages need nothing.
Every page has a Markdown mirror:
the page path plus
.md, with no trailing slash (/cli/commands/is/cli/commands.md).https://docs.nemar.org/llms.txtindexes them. /admin/pages are gated toadminandowner. An admin with a CLI key reads one withnemar admin docs admin/operations/systems-inventory.- If you cannot read something you need, open the issue anyway:
say what you could not read and what you were trying to do, and tag
@nemarOrg/admins(ADR 0057). Escalation replaces read access; silence does not. - Page map, gated pages, retrieval detail:
.rules/docs-site.md.
.context/decisions/ records what was decided and why.
Read the index before designing anything, and before "fixing" something that looks wrong:
several oddities here are deliberate, and the ADR says which.
- Where an ADR and any other doc disagree, the ADR wins.
.context/keeps the analysis; the ADR is the verdict. - Never delete an ADR. Supersede it (ADR 0019 shows what a superseded one looks like).
- Write a new one when a decision is expensive to reverse, closes off other reasonable paths,
has been argued more than once, or encodes a constraint that is not obvious from the code.
Copy
0000-template.md, number sequentially, add it to the index;test/adr-index.unit.test.tsenforces that index and files agree. - The load-bearing ADRs, one line each, are in the index's Load-bearing ADRs section. Read the ones for your area.
nm000103-nm000107 are LIVE (public, DOIs minted).
Do NOT modify their visibility, S3 data, DOIs or repo settings during development or testing.
For end-to-end testing use nm099999 (nemar admin e2e-test; reset with POST /admin/datasets/nm099999/reset).
xx-prefix datasets are blocked from publishing.
Detail: .rules/datasets-and-fixtures.md.
All ids sit inside the 0-99999 cap (xx900001 is invalid).
The top 100 ids of each allocating prefix (nm099900-nm099999, xx099900-xx099999) are RESERVED for standing fixtures and the allocator never returns one (ADR 0068);
fixtures are assigned downward from nm099999, and nm099900 is ABSENT_DATASET_ID, never to be declared dev-owned.
The exemplar fleet (xx0999NN) is permanent.
nm099998 is the standing anonymous deposit: never publish it non-anonymously, a named publication destroys it (ADR 0065).
The band table, the fixture gate and the fixtures: .rules/datasets-and-fixtures.md.
Dev D1 users still holds roughly 609 real email addresses behind a live RESEND_API_KEY, and the nemarDatasets org is shared between prod and dev:
a dev job that selects users by a generic predicate can email real people, and a cascade delete can destroy a real repo.
- Do not re-seed production
nm/dsrows into dev D1 (ADR 0009). - Admin notification mail is production-only (
getAdminEmailsForCategory); setDEV_ADMIN_NOTIFICATIONS=1only for a deliberate staging test.DEV_EMAIL_ALLOWLISTholds exact human addresses, never a domain (@nemar.orghas a catch-all that becomes a production support ticket). - A new daily cron job is production-only BY DEFAULT; the dev cron is a fail-safe allowlist in
scheduled(). - Staging auth uses
TEST_ADMIN_API_KEYfromtest/.env.testwith an isolatedNEMAR_CONFIG_DIR, never a production key. Seeded account kinds and the rest:.rules/environments.md.
ORG_NAME = "nemarDatasets" is correct (nemarOrg holds tooling, nemarDatasets holds dataset repositories):
do not change it to nemarOrg.
EZID is the DOI registrar, not Zenodo (ADR 0007): a DOI change made on the strength of the Zenodo prior art is wrong.
.rules/environments.md.
Ending a credential has to end everything minted from it (the GitHub token, S3 credentials, and the docs and private sessions).
Every route that revokes keys without ending every session calls revokeDocsCredentials.
The docblocks of services/docs-auth.ts and services/private-auth.ts name the callers of their revoke and purge statements;
those counts are load-bearing, so add yourself to them.
A role demotion and an API-key revocation deliberately leave private sessions alone.
Detail: .rules/revocation.md.
package.json version is owned by CI.
Do not edit it and do not run ./scripts/bump-version.sh before a dev to main PR (ADR 0016).
Detail: .rules/release-and-repull.md.
AUTO_REPULL_ENABLED, AUTO_REPULL_MERGE_ENABLED, REPULL_DAILY_OPEN_CAP and REPULL_DAILY_MERGE_CAP stay out of backend/wrangler-sccn.toml (backend/test/repull-switches-flag.test.ts fails a change that adds one);
only the owner adds one, because every re-pull merge mints a version DOI that cannot be withdrawn (ADR 0111).
A manual major bump on an on dataset is refused: plan an upstream re-pull instead.
Detail: .rules/release-and-repull.md.
VECTORIZE_VISIBILITY_FILTER = "1" is set in production [vars] and staging [env.dev.vars], by the owner (ADR 0126); backend/test/vectorize-switch-flag.test.ts fails a change that sets it anywhere else or changes its value.
COMPUTE_ENABLED, COMPUTE_PIPELINES_DISPATCH_ENABLED and COMPUTE_RUNNERS_ENABLED (registered runners; it also needs COMPUTE_ENABLED) are dark switches: they stay out of backend/wrangler-sccn.toml (backend/test/compute-switches-flag.test.ts fails a change that adds one),
and only the owner adds one, in a reviewed pull request that edits that test.
Compute crons are production-only (ADR 0118).
Every sentence about tiers, upload access or a missing field comes from shared/contract/account-copy.ts,
and the ONE gap rule is computeProfileGaps in shared/contract/profile-gaps.ts (ADR 0045).
Change a sentence or a rule there, never at a call site.
Detail: .rules/documentation.md.
Do not edit the primary checkout; concurrent sessions share it: git worktree add <path> -b <branch> origin/dev.
Bun for JavaScript and TypeScript, never npm or npx.
Biome for lint and format, never ESLint or Prettier.
uv for anything Python, never pip or conda.
Wrangler runs through cfman only: bunx cfman wrangler --account sccn <arguments>.
Commands: bun install, bun run src/index.ts (run the CLI from source), bun run typecheck, bun run lint, and bun test (targeted; see Test cost below).
- One change: check the decision index and
.context/plan.md, branch into a worktree, follow.rules/javascript.md, write real tests (.rules/testing.md: NO MOCKS), commit atomically (under 50 characters, no emojis, no co-author tags), open a PR that references the issue, and review it per.rules/code_review.md(at most two rounds, fixes on the PR's own branch). If the change settled something an ADR should own, add or supersede one in the same PR. - Test cost: phases, fixes and review rounds run only targeted tests plus the quick gates,
the full
bun test(about 80 minutes) runs only at epic ->dev, and agents never wait on long jobs (push and report "not run, would check: X because Y"):.rules/testing.md,.rules/ci_cd.md. - Multi-phase work is driven with
/project:epic-dev(--next-phase,--resume,--finalize; inspect with/project:epic-status); never hand-roll an epic, and never let the issues, PRs and.claude/epic.local.mddrift. Phase PRs squash-merge into the epic branch; the epic branch merges intodev; never admin-mergedevormain(.rules/git.md). - The compute program (compute gateway, sign-in provider, third-party compute) runs from its operating manual,
.context/compute-program/README.md: roles, the per-phase loop, the implementer brief and when to escalate.
- Standards:
.rules/(javascript,git,testing,code_review,documentation,ci_cd, and the hard-rule detail files linked above). Platform reference: docs.nemar.org via.rules/docs-site.md;nemar <group> --helpis authoritative for commands. - Observations:
.memory/, one per file, binding nobody (an ADR is a ruling, a.context/document an argument, a memory an observation). Plans and research:.context/README.mdmarks what is current and what is historical; start fromplan.md,ideas.mdandresearch.md(prior art from before NEMAR, not the production path).