docs(#40): add country implementation template (#161)

* docs(#39): add contributor setup guide

* refactor(#39): simplify contributor guide

* fix(#39): repair basic usage example and document registry count

The contributor guide advertises npm run example, which failed to
compile due to an always-true guard on a non-optional checksum
function. Fix the guard and cover both TypeScript examples in the
examples-check job so the scripts cannot rot undetected again.

Also document the primary-key count assertion contributors must
update when adding a country, and list adapters.ts in the project
structure.

* docs(#40): add country implementation template

Add docs/COUNTRY_TEMPLATE.md: a copy-paste module template and submission
checklist for contributors adding a new country validator.

Derived from the current codebase rather than the issue's original sketch:

- Module template models kaz/ and lva/ (the most recently added countries):
  function-based module, IdMetadata-typed METADATA, validate() delegating to
  parse(), country-shared helpers in util.ts.
- Documents both accepted METADATA shapes (IdMetadata vs the legacy
  isParsable/hasChecksum/pattern form normalized by registry/adapters.ts) and
  recommends the canonical, explicitly annotated one.
- Records the four registration touchpoints (registerAll.ts COUNTRY_REGISTRY,
  the index.ts namespace export, and the SUPPORTED_COUNTRIES entry that feeds
  getCountryIdFormat), plus the hard-asserted 80-key registry invariant and the
  fixtures that must move with it.
- States that the Python idnumbers library is the source of truth and maps its
  per-country layout onto this repo's.
- Notes the unquoted format:check glob so contributors verify their own files.

The template's TypeScript is verified: it typechecks, passes ESLint and
Prettier, and its METADATA.example validates via validateNationalId.

Link the template from the Validator Organization section of CONTRIBUTING.md.

* docs(#40): correct template claims about layout and CI

Review of the template found four inaccurate claims. Each replacement was
re-verified against the codebase.

Directory layout: the guide claimed the primary ID type belongs directly in
index.ts and that re-export-only directories predate that convention. Both were
false. Re-export-only is the majority (49 of 80; 31 define the primary in
index.ts), and no convention history exists -- all 80 primary modules landed in
the initial release, aeaf7db. Present both layouts as valid and recommend by
country shape: primary in index.ts for a single ID type, a named file once the
country has several.

Function-based guidance kept, evidence corrected. KAZ and LVA are not the newest
countries; they date from the initial release like all 80, and their 2026 commit
added secondary modules. The claim now rests on the real measurement: all 12
country modules written in 2026 are function-based, the newest being
nzl/irdNumber.ts. Also stop implying the class shape is absent -- classes with
static readonly METADATA are common (zwe/nationalId.ts); it is the issue's
static readonly PATTERN that exists nowhere, as the regex lives in
METADATA.regexp.

getCountryIdFormat fallbacks: only countryName falls back to the country code.
idType falls back to METADATA.names[0]. Name both.

Registration: reframe "four places" as three edits plus one prohibition, since
keeping secondary types out of the registry is a rule, not a file to touch.

Verification: scope the "CI runs exactly these" claim to the quality-checks gate
job and note the build, coverage, and examples jobs that can still fail a change
which passes all four locally.

Sharpen the METADATA-shape warning with the verified failure mode: adapters.ts
resolves a misspelled `pattern` to `?? /./`, so the registry reports a
match-anything regex rather than raising a compile error. Cross-reference #160.

Author: AngusHsu

CONTRIBUTING.md

@@ -175,6 +175,8 @@ The primary validator provides:
 
 A country directory may contain additional files for secondary ID types or historical formats. Shared country-specific helpers belong in `util.ts` only when multiple validators in that country need them. Reuse `src/utils.ts`, `src/constants.ts`, and `src/types.ts` for cross-country behavior instead of duplicating common logic.
 
+Adding a country? [docs/COUNTRY_TEMPLATE.md](docs/COUNTRY_TEMPLATE.md) provides a copy-paste module template, the registration touchpoints, and a submission checklist.
+
 ### Registry Flow
 
 Importing `src/index.ts` loads `src/registry/registerAll.ts` as a side effect. `registerAll.ts` adapts the supported validator styles, registers one primary validator per country in the `ValidatorRegistry` singleton, and registers supported aliases.